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Introduction 


The  Commodore  128  is  the  latest  in  Commodore's  remarkable  line  of  8 -bit 
home  computers.  Like  its  predecessors,  the  VIC-20  and  the  Commodore  64,  it 
is  a  remarkable  computer.  Despite  its  low  price  and  small  size,  it  has  more 
features  than  most  larger  and/ or  more  expensive  computers. 

If  you  want  to  solve  math  problems,  the  C-128  can  run  them  for  you.  If 
you  need  to  type  letters  or  mailing  lists,  the  C-128  will  do  the  job  quickly  and 
easily. 

But  in  addition  to  these  functions,  common  to  most  computers,  the 
C-128  offers  color  text  and  bit-mapped  graphics. 

Furthermore,  the  C-128  can  produce  high-fidelity  sound  within  a  range 
of  nine  octaves.  These  can  be  combined  to  produce  music  or  voices  or  to  imitate 
anything  from  the  patter  of  rain  to  a  cannonade. 

Chapter  1  explains  how  to  unpack  and  set  up  the  C-128  and  its  accesso- 
ries. It  contains  a  description  of  all  the  controls  on  the  computer,  from 
connectors  to  keyboard  functions. 

Chapter  2  guides  you  through  the  C-128  screen  editor  and  explains  the 
two  operating  modes  of  the  C-128:  immediate  mode  and  programmed  mode. 
This  is  followed  by  an  introduction  to  the  Datassette,  the  1571  disk  drive,  and 
the  MPS  803  printer. 
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Chapter  3  introduces  you  to  programming.  All  the  most  commonly  used 
BASIC  instructions  are  covered  as  well  as  the  concepts  of  loops,  branching, 
Boolean  operators,  floating  point  versus  integer  numbers,  and  scientific 
notation.  The  chapter  also  describes  variable  types  and  the  construction  of 
arrays. 

Advanced  BASIC  programming  is  the  subject  of  Chapter  4.  It  will  teach 
you  practical  applications  of  concepts  covered  in  Chapter  3.  You  will  learn 
how  to  write  screen  display  programs,  include  cursor  movement  and  string 
variables  as  commands  in  your  programs,  and  develop  easy-to-use  I/O 
intensive  programs  requiring  considerable  data  entry.  Chapter  4  also  dis- 
cusses the  C-128's  real  time  clock  and  random  number  generator. 

Chapter  5  is  a  tutorial  on  game  controllers.  It  will  show  you  how  to  use 
the  keyboard  as  a  game  controller  and  how  to  write  programs  that  access  a 
joystick  or  paddle  controller. 

Chapter  6  covers  graphics.  It  explains  how  the  video  display  works,  how 
colors  are  produced,  and  how  to  put  characters  on  the  screen.  You  will  learn 
how  to  animate  pictures  and  produce  high-resolution  graphics  using  BASIC. 

Chapter  7  discusses  sound  generation  on  the  C-128,  including  the  C-128 
sound  registers  (the  components  of  sound)  and  how  to  use  them.  You  will 
learn  how  to  program  music  into  the  C-128  and  how  to  save  it  for  playback 
later  on. 

Chapter  8  explains  the  operation  of  the  major  C-128  peripherals:  The 
Datassette,  1571  disk  drive,  and  MPS  803  printer.  It  contains  a  complete 
discussion  of  data  file  creation,  program  storage,  and  high-level  disk  opera- 
tions. It  also  discusses  all  the  printer  commands,  including  double-width 
characters,  reverse  printing,  and  high-resolution  graphics. 

Chapter  9  is  a  reference  to  using  the  built-in  C-128  machine  language 
monitor  and  mini-assembler.  It  also  contains  a  complete  listing  of  8502 
machine-code  instructions. 

Chapter  10  discusses  the  use  of  CP/M-PLUS  and  how  this  operating 
system  opens  the  door  to  thousands  of  powerful  business  and  personal 
programs.  It  also  describes  all  of  the  system  commands  and  instructions. 

The  appendixes  contain  tables  on  all  the  details  discussed  in  the  text, 
from  the  system  architecture  and  block  diagrams  to  the  memory  maps.  You 
will  also  find  diagrams  showing  pinouts  for  all  of  the  connectors  as  well  as 
color,  screen,  and  sound  value  tables. 


CHAPTER 


Introducing  the 
Commodore- 128 
Computer 


When  you  first  unpack  the  C-128,  you  will  find  the  equipment  shown  in 
Figure  1-1: 

•  The  C-128  computer 

•  Power  supply  (large  plastic  box) 

•  TV  switch  box 

•  Video  cable 

•  Three  system  diskettes 

Your  system  may  include  additional  components,  but  all  systems  include 
this  basic  equipment.  This  chapter  identifies  each  component  and  connector 
provided  by  Commodore  and  introduces  the  function  of  each. 

Place  the  C-128  on  a  flat  surface  such  as  a  table.  Make  sure  that  you  have 
room  to  put  a  television  near  the  C-128,  ideally  directly  behind  it. 
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FIGURE  1-1.  Equipment  packed  with  the  C-128 


REAR  AND  SIDE  PANELS 

All  of  the  switches,  connectors,  and  interfaces  are  located  at  the  side  and  back 
of  the  C-128  computer.  These  components  are  labeled  in  Figure  1-2.  It  is 
important  that  you  learn  the  function  and  location  of  each  component  as  you 
hook  up  the  computer;  if  you  connect  the  components  incorrectly,  you  may 
damage  the  computer. 

Power  Switch 

Make  sure  the  C-128  is  OFF  at  this  point.  The  power  switch  is  located  on  the 
right  side  of  the  computer.  It  is  a  two-position  "rocker"  switch. 

When  you  turn  the  power  switch  ON,  the  C-128  will  display  a  dark  screen 
for  a  short  time.  During  this  period,  it  is  initializing  itself;  that  is,  it  is  checking 
out  its  internal  systems  and  memory. 
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FIGURE  1-2.  Rear  and  side  views  of  the  C-128 


When  you  turn  the  power  OFF,  all  programs  and  data  in  memory  that 
were  not  stored  onto  either  diskette  or  tape  will  be  lost. 

Power  Connector 

The  power  supply  has  two  cables  attached  to  it.  One  plugs  into  any  standard 
HO-volt  AC  outlet.  The  other  plugs  directly  into  the  power  connector  next  to 
the  ON/ OFF  switch  on  the  side  of  the  C-128. 

Game  Ports 

These  connectors  are  used  for  the  various  game  controllers  available  for  the 
C-128,  as  well  as  for  the  light  pen  and  some  special  application  devices. 
ATARI  joysticks  and  paddles  will  work  with  this  port,  as  well  as  those  made 
by  Commodore. 

Parallel  User  Port 

The  parallel  user  port  is  a  connector  that  allows  you  to  hook  up  devices  (such 
as  the  Commodore  modem)  to  the  C-128. 

More  advanced  users  may  use  this  connector  for  custom  applications  as 
well,  since  the  signals  coming  from  it  can  be  programmed  directly  by  the 
C-128. 
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Cassette  Interface 

The  cassette  interface  is  used  to  connect  the  Datassette,  which  is  a  special 
digital  tape  recorder.  You  can  use  the  Datassette  to  store  and  reload  programs 
and  data  into  the  C-128.  The  Datassette  is  described  later  in  this  chapter. 

Serial  Port 

The  serial  port  is  used  to  connect  the  computer  to  the  model  MPS  803  printer, 
the  1571  disk  drive,  and  other  devices  using  a  serial  input/output  configura- 
tion. Instructions  for  connecting  the  printer  and  disk  drive  to  the  C-128  are 
provided  later  in  this  chapter. 

Video  Ports 

The  C-128  has  three  video  ports: 

•  Modulated  (TV)  video 

•  Composite  video 

•  RGB 

These  ports  allow  you  to  connect  the  C-128  to  either  a  standard  television,  a 
composite  monitor,  or  a  high-resolution  RGB  monitor.  Depending  upon  the 
mode  you  are  using,  the  C-128  will  send  its  video  signal  or  signals  to  one  or 
more  of  these  ports. 

When  used  with  a  television  or  a  composite  monitor,  the  C-128  produces 
the  sound  and  pictures  displayed  on  your  television  by  combining  them  into  a 
signal  called  composite  video.  This  signal  is  sent  out  through  the  video  port. 

A  video  monitor  (a  television  without  a  tuner)  is  able  to  convert  the 
composite  video  directly  into  pictures  and  sound.  Connect  a  monitor  to  the 
monitor  video  port.  A  television,  however,  must  be  tuned  to  a  particular 
channel.  That  signal  is  produced  and  combined  with  the  composite  video  by 
the  built-in  RF  (radio  frequency)  modulator.  Connect  your  TV  to  the  TV 
video  port. 

When  you  use  the  C-128,  you  can  select  either  channel  3  or  channel  4  by 
flipping  the  channel  switch  on  the  back  of  the  computer. 

Expansion  Interface 

The  expansion  interface  gives  you  access  to  the  computer's  memory  lines. 
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a.  8  X  8  dot  matrix               b.  Sample  letter  A                c.  Sample  graphic 

FIGURE  1-3.  The  8X8  dot  matrix 


Video  Display 

Depending  upon  the  mode  you  select  (40-column  or  80-column)  when  you 
first  power  up  the  C-128,  it  displays  either  25  rows  with  40  characters  per  row 
or  25  rows  with  80  characters  per  row.  The  computer  generates  these  charac- 
ters by  lighting  the  appropriate  pattern  of  dots  within  an  8  X  8  matrix.  This  is 
illustrated  in  Figure  1-3.  The  C-128's  character  set  is  quite  extensive,  contain- 
ing 256  letters,  numbers,  and  symbols.  It  is  also  possible  to  program  custom 
characters  for  special  applications.  This  will  be  discussed  in  Chapter  6. 


POWER  UP 

Connect  the  TV  switch  box  to  the  back  of  the  television  by  attaching  one  end 
of  the  cable  with  the  phono  jacks  (Figure  1-4)  to  the  switch  box. 

Connect  the  larger  plug  of  the  video  cable  to  the  round  five-pin  video 
port  on  the  back  of  the  C-128  (see  Figure  1-2). 

Finally,  plug  the  power  supply  cord  into  the  C-128  power  connector.  Do 
not  turn  on  the  C-128  yet! 

To  start  using  your  C-128,  follow  these  steps: 

1.  Plug  the  AC  power  cord  into  a  wall  outlet. 

2.  Switch  the  power  ON.  The  power  switch  is  located  on  the  right  side 
near  the  AC  plug. 

3.  Wait  for  the  READY  display.  This  can  take  several  seconds,  during 
which  the  C-128  is  going  through  a  self-checking  and  initialization 
process. 
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FIGURE  1-4-  Television  switch  box  and  connections 


The  following  display  should  now  appear: 


COMMODORE  BASIC  V7.0   122365  BYTES  FREE 
(C) 1985  COMMODORE  ELECTRONICS,  LTD. 
(0  1977  MICROSOFT  CORP. 
ALL  RIGHTS  RESERVED 


READY. 
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If  you  do  not  get  this  display,  turn  the  power  OFF,  wait  about  ten  seconds, 
and  turn  the  power  ON  again.  If  you  still  don't  get  this  display,  check  the 
connections.  If  that  does  not  help,  contact  your  Commodore  dealer. 


THE  KEYBOARD 

In  almost  every  application,  the  keyboard  is  used  to  communicate  with  the 
C-128.  The  keys  are  arranged  much  like  those  on  a  standard  typewriter. 
Unlike  typewriter  keys,  however,  many  of  the  C-128's  keys  can  be  used  to 
access  as  many  as  three  or  four  different  symbols,  characters,  or  functions. 
The  keys  on  the  C-128  may  be  classified  by  function  as  follows: 

•  Alphabetic  keys 

•  Numeric  keys 

•  Special  symbol  keys 

•  Graphic  keys 

•  Function  keys 

•  Cursor  control  keys 

Alphabetic  Keys 

The  alphabetic  keys  include  the  26  letters  of  the  alphabet  in  both  upper-  and 
lowercase.  When  the  C-128  is  powered  up,  letters  are  displayed  in  uppercase. 
To  display  lowercase  letters,  press  the  COMMODORE  and  SHIFT  keys 
simultaneously.  If  you  are  typing  lowercase  letters  and  wish  to  insert  an 
occasional  uppercase  letter,  use  the  SHIFT  key  as  you  would  on  a  typewriter. 
Press  SHIFT-COMMODORE  again  to  return  to  uppercase  mode. 


bbbb  easa  mm 
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Numeric  Keys 

The  numeric  keys  are  used  to  enter  the  digits  0  through  9.  You  may  enter 
numbers  from  either  the  keyboard  or  the  numeric  keypad,  which  is  to  the 
right  of  the  keyboard. 


Special  Symbol  Keys 

The  special  symbol  keys  include  the  following  standard  punctuation  marks:  ! 
"'.,;:?.  They  also  include  the  following  mathematical  symbols:  +  =  /  *  t  -. 
(Note  that  a  slash  is  used  for  division,  an  asterisk  for  multiplication,  and  an  up 
arrow  for  exponentiation.)  Other  special  symbols  available  on  the  C-128 
include  #$&  @  %£  7T  <>[] 


Graphic  Keys 

The  C-128  also  has  62  graphic  symbols  that  may  be  accessed  through  the 
shift  or  COMMODORE  function  keys.  Using  these  graphic  symbols,  you  can 
create  fairly  sophisticated  display  drawings. 

The  graphic  symbols  and  their  names  are  listed  in  Table  1-1.  Similar 
symbols  have  been  grouped  to  make  graphic  options  immediately  obvious. 
Note  that  the  square  enclosing  each  of  the  graphic  symbols  shown  in  Table  1  - 1 
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TABLE  1-1.  Graphic  Character  Keys 


Line 
Horizontal 


fa" 
E 


Top 

3/4  Top 

2/3  Top 


[§]  Near  Middle 


pf~]  Middle 


2/3  Bottom 
3/4  Bottom 
Bottom 


Line 
Vertical 


Left 

3/4  Left 

2/3  Left 
Near  Middle 
Middle 
2/3  right 
3/4  right 


(J)  Right 


Thin 
Bar 


Top 

Bottom 
Left 


(3D  Rl*ht 


Thick 
Bar 


nr 


Top 


Bottom 


Left 


Right 


Half 
Block 


Left 


*  Bottom 


Triangle 
Solid 


Quarter  Block 
Solid 


lYJlc 


Top  Left, 
Top  Right 


Quarter  Block 
Open  (Angle) 


Corner 

.  O   l  IP; 


Rounded 
Corner 


Suit 


Top  Left  Spade,  Heart 


Top  Right 


Diamond, 
Club 


rj  ]  Bottom  Left, 
PJ   Bottom  Right 


Diagonal 


Top 

Bottom 
Left 

Right 


Top  Left, 
Top  Right 

Bottom  Left, 
Bottom  Right 


Top  Left, 
Top  Right 

Bottom  Left, 
Bottom  Right 


Top  Left, 
Top  Right 

Bottom  Left, 
Bottom  Right 


Symbol 


Grid 


Cross 


Diagonal 
Acute 

Diagonal 
Grave 


Full 


Half  Left 


Hi  Half 
Bottom 


Circle 


Outline 


Solid 
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and  Figure  1  -  3  is  not  actually  part  of  the  symbol,  but  has  been  added  to  show 
the  symbol's  location  within  its  8  X  8  grid. 


Function  Keys 

Any  key  that  "does  something,"  rather  than  "prints  something,"  is  a  function 
key.  For  instance,  CTRL-RED  (pressing  the  CTRL  and  RED  keys  simultane- 
ously) doesn't  print  anything,  but  instead  causes  all  subsequent  characters  to 
be  displayed  in  red  on  the  screen. 


RUN/ STOP 


/ 


shift  lock   Color  Control  Keys 

ffffi  IRRRR 


RESTORE 


SHIFT 


SHIFT  RETURN 


SHIFT 

The  SHIFT  key  is  used  in  conjunction  with  any  other  key  on  the  keyboard 
to  access  that  key's  "shifted"  function  or  character.  Most  keys  have  both  a 
shifted  and  unshifted  character  or  function.  For  example,  shifted  lowercase 
letters  become  uppercase  letters,  and  a  shifted  CRSR  UP/ DOWN  causes  the 
cursor  to  move  up. 
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There  are  two  identical  SHIFT  keys  on  the  C-128  keyboard.  One  is  at  the 
lower-left  corner  of  the  keyboard,  while  the  other  is  at  the  lower-right. 

SHIFT  LOCK 

You  may  occasionally  need  a  continuous  string  of  shifted  characters.  To 
make  this  operation  easier,  the  C-128  has  a  SHIFT  LOCK  key  that  is  similar  to 
the  shift  lock  on  a  typewriter.  Pressing  the  SHIFT  LOCK  key  until  it  clicks  will 
lock  the  keyboard  into  shifted  mode.  Pressing  it  until  it  clicks  again  will 
unlock  the  shifted  mode. 

Unless  the  C-128  is  running  a  program,  RUN/ STOP  does  nothing. 
Pressing  SHIFT  and  RUN/  STOP  loads  and  executes  a  program  from  the  C-128 
Datassette. 

RETURN 

The  RETURN  key  is  much  like  the  carriage  return  key  on  a  typewriter.  It 
causes  the  cursor  (the  flashing  square  that  indicates  where  the  next  character 
will  appear)  to  return  to  the  left-hand  margin  of  the  next  line. 

The  RETURN  key  is  also  used  to  enter  instructions  in  BASIC.  After 
keying  in  a  line  of  your  program,  you  press  RETURN  to  enter  that  line  into 
memory. 

A  RETURN  executed  while  the  cursor  is  on  the  bottom  line  of  the  screen 
will  cause  the  entire  screen  to  scroll  up,  moving  the  cursor  to  the  beginning  of 
the  new  blank  line  generated  by  the  scroll. 


10  PRINT  "NOW  IS  THE" 
20  PRINT  "TIME  FOR" 
38  PRINT  "ALL  GOOD" 
40  PRINT  "PEOPLE" 
50  READ  X 
90  R=B+C+D 
100  IF  flsl  THEN  10 
110  IF  fl*20  THEN  50 
120  PRINT  "START" 
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28  PRINT  "TIME  FOR" 
30  PRINT  "ALL  GOOD" 
40  PRINT  "PEOPLE" 
50  RERD  X 
90  fl=B+C+D 
100  IF  fl=l  THEN  10 
110  IF  fl=20  THEN  50 
120  PRINT  "START" 


REVERSE  ON/OFF 

The  RVS  ON  and  RVS  OFF  keys  allow  you  to  reverse  the  light  and  dark 
parts  of  the  screen.  The  default  mode  for  this  function  is  RVS  OFF.  The  RVS  ON 
is  like  the  negative  of  a  photograph.  To  reverse  the  characters,  press  CTRL  and 
RVS  ON  at  the  same  time.  All  subsequent  characters  entered  will  be  displayed 
in  reverse.  To  switch  back  again,  press  CTRL  and  RVS  OFF. 


NORMAL  PRINT  slslMslr&sMSMHfl 


I      RVS  1 


RUN/STOP 

In  the  unshifted  mode,  the  RUN/ STOP  key  will  stop  any  program  that  is 
being  executed,  returning  control  of  the  computer  to  the  keyboard.  It  will  also 
display  the  number  of  the  program  line  that  was  being  executed  before  the 
stop  instruction  was  received. 

To  demonstrate  this,  enter  the  following  short  program: 

10  X  *  0 
20  PRINT  X 
30  X  *  X  +  1 
40  GOTO  20 
99  END 
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Now  type  RUN  and  press  RETURN.  You  should  see  a  string  of  numbers 
scrolling  down  the  left  side  of  your  screen.  After  pressing  run/ STOP,  your 
screen  should  look  like  the  following: 

0 

1 

eL 

3 
4 


10 
11 
12 
13 
14 
15 
16 
17 
18 

BREAK  IN  20 
■ 

Unless  the  C-128  is  running  a  program,  RUN/ STOP  does  nothing. 
Pressing  SHIFT  and  RUN/  STOP  loads  and  executes  a  program  from  the  C-128 
Datassette. 

RESTORE 

If  pressing  the  RUN/ STOP  key  alone  does  not  stop  a  program,  then  press 
RUN/ STOP  and  RESTORE  simultaneously.  If  this  does  not  work,  turn  the 
power  OFF  and  then  ON. 

COLOR  CONTROL  KEYS 

Along  the  top  of  the  keyboard,  just  under  number  keys  1-8,  are  located 
the  eight  color  control  keys:  black,  white,  red,  cyan  (light  blue),  purple, 
green,  blue,  and  yellow.  These  keys  change  the  color  of  the  characters  being 
typed  on  the  display.  To  use  these  keys,  you  must  press  CTRL  and  the  color 
you  wish  to  use.  For  example,  when  you  first  power  up  the  C-128,  your  screen 
comes  up  with  a  cyan  border,  blue  inner  field,  and  light-blue  letters.  By 
pressing  CTRL  and  PUR  together,  you  will  begin  typing  purple  letters.  By 
pressing  the  COMMODORE  key  and  color  keys  together,  you  can  get  eight 
more  colors. 
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Cursor  Control  Keys 

The  remaining  keys  move  the  cursor. 


CURSOR 
LEFT     CURSOR  RIGHT 

CURSOR  DOWN 
CURSOR  UP  11/    INSERT  DELETE 


CLEAR  HOME  CURSOR 
UP  DOWN 


CURSOR 
LEFT  RIGHT 


CLEAR  HOME 

In  the  unshifted  mode,  pressing  the  CLR  HOME  key  will  make  the  cursor 
jump  to  the  top  left-hand  corner  of  the  screen  (the  home  position).  To 
demonstrate  this,  type  LIST  and  press  RETURN.  You  should  see  a  listing  of  the 
program  you  entered  in  the  last  section.  If  you  turned  the  computer  OFF  since 
entering  the  program,  reenter  it  now.  After  typing  LIST,  you  will  find  the 
cursor  beneath  the  listing,  after  the  word  READY. 


10   X   =  0 

20  PRINT  X 
30  X  *  X  +  1 
40  GOTO  20 
99  END 
■ 
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Press  the  CLR  HOME  key.  The  cursor  should  jump  to  the  top  left-hand 
corner  of  the  screen. 


In  the  shifted  mode,  the  CLR  HOME  key  will  not  only  return  the  cursor  to 
the  home  position,  but  it  will  also  erase  anything  that  was  on  the  screen  (that 
is,  it  will  clear  the  screen).  Type  LIST  again.  Now  press  SHIFT  and  press  CLR 
HOME  simultaneously. 
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CURSOR  UP/DOWN 

In  the  unshifted  mode,  the  CRSR  UP/  DOWN  key  causes  the  cursor  to 
move  down  the  screen  a  single  line.  Holding  down  the  CRSR  UP/ DOWN  key 
causes  the  cursor  to  move  downward  until  it  reaches  the  bottom  of  the  screen. 
If  the  cursor  is  on  the  bottom  line  of  the  screen  and  the  unshifted  CRSR 
UP/ DOWN  is  pressed,  the  entire  screen  will  be  scrolled  up  and  the  cursor  will 
be  positioned  at  the  bottom  line. 

LIST  your  program  again.  Now  press  the  CRSR  UP/ DOWN  key  several 
times,  or  hold  it  down.  When  the  cursor  reaches  the  bottom  of  the  screen,  all 
the  lines  on  the  screen  will  move  up  from  one  to  four  lines.  This  happens 
because  the  logical  length  of  the  lines  is  80  characters,  but  the  display  may  be 
either  40  or  80  characters  wide.  The  logical  length  of  a  line  is  the  number  of 
characters  the  C-128  can  handle  internally  on  each  numbered  line.  Therefore, 
depending  on  how  much  of  a  line  is  left  when  the  cursor  reaches  the  bottom  of 
the  screen  (regardless  of  what  is  actually  displayed),  the  screen  will  scroll  up 
one  logical  line,  producing  an  effective  scroll  of  one  to  four  partial  lines. 


26  PRINT  X 
30  X  =  X  +  1 
40  GOTO  20 
99  END 
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In  the  shifted  mode,  the  CRSR  UP/ DOWN  key  moves  the  cursor  up  one 
line  at  a  time.  When  the  cursor  reaches  the  top  of  the  screen,  it  stays  there.  The 
screen  will  not  automatically  scroll  down  (move  all  the  lines  down  one  or 
more  positions). 

CURSOR  LEFT/RIGHT 

In  the  unshifted  mode,  the  CRSR  LEFT/ RIGHT  key  will  move  the  cursor 
right  one  character  position.  Press  the  CRSR  LEFT/ RIGHT  key  and  hold  it 
down.  Notice  what  happens  when  the  cursor  reaches  the  end  of  a  line.  It 
jumps  to  the  leftmost  position  of  the  next  line  down. 


10  PRINT  "THE  QUICK  BROWN  FCl« 
JUMPED  OVER  THE  DOG" 
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r 


10  PRINT  "THE  QUICK  BROWN  FOX 
■JUMPED  OVER  THE  DOG" 


Pressing  the  SHIFT  and  CRSR  keys  together  will  move  the  cursor  left  one 
character  position.  When  the  cursor  reaches  the  left-hand  border,  it  jumps  to 
the  rightmost  column  of  the  next  line  up.  This  is  called  wraparound.  It  allows 
you  to  continue  entering  lines  that  are  more  than  the  width  of  the  screen 
without  pressing  RETURN.  This  is  similar  to  having  an  automatic  carriage 
return. 

If  the  cursor  is  at  the  right-hand  edge  of  the  bottom  line  and  CRSR  RIGHT 
is  pressed,  the  screen  will  scroll  up  a  line.  The  wraparound  feature  advances 
the  cursor  to  the  beginning  of  the  next  line,  effectively  producing  a  CRSR 
DOWN. 

The  CRSR  UP/ DOWN  and  CRSR  LEFT/ RIGHT  keys  are  used  to  move  the 
cursor  over  text  without  changing  the  text.  To  alter  the  text,  move  the  cursor 
to  the  character  you  wish  to  correct.  Typing  another  character  will  replace  the 
existing  one,  allowing  you  to  edit  text  easily  on  the  screen. 

INSERT/DELETE 

The  INS/ DEL  key  is  used  to  insert  or  delete  characters  on  the  screen.  In 
the  unshifted  mode,  the  INS/ DEL  key  deletes  the  character  to  the  left  of  the 
cursor.  It  also  moves  the  rest  of  the  characters  in  the  line  one  space  left  and 
adjusts  any  other  characters  in  the  80-column  logical  line  of  which  it  is  a  part. 

10  PRINT  "BIG  BROOXrr 
10  PRINT  "BIG  BR0H1" 
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If  you  press  SHIFT  and  INS/  DEL  together,  the  computer  will  insert  a  space 
on  the  screen.  All  characters  to  the  right  of  the  cursor  will  be  moved  one 
position  to  the  right. 

10  R=B+C+D-<4iS  /F) 


PROGRAMMABLE  FUNCTION  KEYS 

In  addition  to  the  keys  just  covered,  the  C-128  has  four  programmable, 
dual-function  keys.  They  are  labeled  F1/F2,  F3/F4,  F5/F6,  and  F7/F8.  The 
functions  of  these  keys  are  specified  by  the  user. 


Programming  the  Function  Keys 

Most  of  the  function  keys  can  be  put  into  PRINT  statements  in  the  program 
mode.  For  instance,  instead  of  pressing  CTRL  and  RED  in  the  immediate  mode 
to  print  in  red,  you  could  put  the  control  functions  in  a  PRINT  statement  such 
as 

10  PRINT  ,,(CTPLXCVflN)HPPPV  VRLENTINES  DRV < CTRL >  ( REP )  < HEART > " 

When  you  RUN  this  line,  it  will  print  the  words  HAPPY  VALENTINE'S 
DAY  in  light  blue  (cyan),  followed  by  a  red  heart. 

With  the  exception  of  SHIFT,  SHIFT  LOCK,  ^  RETURN,  RUN/ STOP,  and 
RESTORE,  any  of  the  function  keys  can  be  programmed  into  PRINT 
statements. 

When  the  function  keys  are  programmed  into  PRINT  statements,  they 
appear  on  the  screen  as  reverse  characters.  Table  1-2  shows  these  symbols. 
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TABLE  1-2.  Special  Function  Keys 


Li 

CLEAR  SCREEN 

CYAN 

B 

fi 

HOME 

a 

PURPLE 

n 

f2 

□ 

CURSOR  UP 

n 

GREEN 

H 

f3 

CURSOR  DOWN 

□ 

BLUE 

B 

f4 

1 1 

CI  I  RSOR  I  FFT 

mi 

EJJ 

YELLOW 

i  ■ 

f5 

El 

CURSOR  RIGHT 

Ld 

REVERSE  ON 

a 

f6 

■ 

BLACK 

B 

REVERSE  OFF 

ii 

f7 

S 

WHITE 

□ 

DELETE 

H 

f8 

s 

RED 

THE  COMMODORE  1530  DATASSETTE 

You  will  soon  find  that  entering  all  of  your  programs  by  hand  is  tedious.  A 
data  recorder  will  solve  this  problem.  In  addition  to  the  Commodore 
Datassette,  there  are  two  similar  units  that  will  work  with  your  C-128.  One  is 
the  original  PET/CBM  digital  cassette  drive,  and  the  other  is  the  Commo- 
dore 1530  Datassette  (Figure  1-5).  One  advantage  the  Datassette  has  over  the 
older  unit  is  a  tape  counter.  This  makes  it  easier  to  locate  programs  on  your 
tapes.  The  operation  and  installation  of  these  two  units  is  the  same.  To  use 
them,  follow  these  instructions. 

Look  at  the  cassette  interface  on  the  back  of  the  C-128  (Figure  1-2).  The 
connector  has  an  offset  slot  between  two  of  the  contacts,  as  shown  in  Figure 
1-6. 

The  Datassette  has  a  plug  with  a  divider  that  fits  over  the  connector  and 
into  the  slot.  This  makes  it  difficult  to  connect  it  incorrectly,  but  it  can  be 
done,  so  be  careful.  In  general,  you  may  find  a  connector  difficult  to  remove 
once  it  is  on,  but  it  is  rare  to  have  trouble  installing  one  if  it  is  positioned 
correctly.  If  the  divider  slides  over  the  slot,  you  can  be  sure  a  proper  connec- 
tion has  been  made. 

To  connect  the  Datassette  to  the  C-128,  follow  these  steps: 

1 .  Turn  the  power  OFF. 

2.  Hold  the  plug  so  the  divider  will  mate  with  the  connector  slot. 
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FIGURE  1-6.  Datassette  connector 
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3.  Gently  push  the  plug  onto  the  interface.  Do  not  force  the  connection. 

4.  Make  sure  the  connection  fits  securely. 

5.  Turn  power  ON. 

Testing  the  Datassette 

Before  you  go  any  further,  you  should  check  the  mechanical  operation  of  the 
Datassette.  Here  is  a  simple  test  you  can  use  to  make  sure  that  all  of  the 
control  functions  are  operating  properly. 

1.  Turn  the  C-128  ON.  Make  sure  that  none  of  the  cassette  keys  are 
depressed  and  that  the  cassette  drive  motor  is  not  running. 

2.  Open  the  cassette  door  located  on  the  top  of  the  unit  by  pressing  the 
STOP/EJECT  key  on  the  Datassette.  While  looking  inside  the  unit, 
press  the  PLAY  key  on  the  Datassette.  You  should  see  the  tape  heads 
(Figure  1-7)  move  out  toward  the  spindles.  At  the  same  time,  the 
pinch  roller  should  move  out,  touch  the  capstan  roller,  and  begin 
rotating  counterclockwise. 

3.  Again  press  the  STOP/ EJECT  key  on  the  Datassette.  The  tape  heads 
should  pop  back  out  of  view  and  the  spindles  should  stop  rotating. 

4.  Press  the  F.FWD  (Fast  Forward)  key.  The  tape  heads  should  remain 
hidden,  and  the  take-up  spindle  (on  the  right)  should  begin  spinning 
counterclockwise  very  fast. 

5.  Pressing  STOP/ EJECT  once  should  stop  the  take-up  spindle. 

6.  Press  the  REW  (Rewind)  key.  The  supply  spindle  (on  the  left)  should 
begin  spinning  clockwise  very  fast. 


FIGURE  1-7.  Datassette  drive  tape  head 


INTRODUCING  THE  C-128  COMPUTER  23 


FIGURE  1-8.  Write-protect  notches 


7.  Press  the  STOP/ EJECT  key  once.  The  supply  spindle  should  stop 
spinning. 

8.  Very  gently  press  the  REC  (Record)  key.  The  key  should  be  locked. 

9.  Get  an  unused  tape.  Look  at  the  back  of  the  cassette.  It  should  have 
two  small  tabs  blocking  the  write-protect  holes  (Figure  1-8). 

Pressing  the  PLAY  and  RECORD  keys  simultaneously  should  start  the  take-up 
spindle  rotating;  the  head  assembly  should  move  out  and  contact  the  tape, 
which  should  start  moving. 

If  you  can  perform  all  these  steps,  your  cassette  recorder  is  ready  to  begin 
operation.  If  some  or  all  of  the  steps  of  the  test  fail,  check  the  following: 

•  Make  sure  the  power  is  ON. 

•  Press  only  one  key  at  one  time  (except  when  checking  the  record 
function). 

•  Press  the  keys  down  until  they  click  into  place. 

If  you  are  still  unsuccessful,  contact  your  Commodore  dealer. 

Cleaning  and  Demagnetizing 
Tape  Heads 

The  head  assembly  of  the  Datassette  can  be  seen  by  opening  the  drive  door 
with  the  power  OFF  and  depressing  the  PLAY  key.  Doing  this  will  allow  you 
access  to  the  heads  for  maintenance.  Refer  to  Figure  1-7  for  the  locations  of 
the  components  mentioned  in  this  section. 


24     C- 128  USER  GUIDE 


The  tape  heads  are  the  devices  that  make  contact  with  the  tape  and  either 
read  or  write  data.  Since  the  tape  is  actually  in  contact  with  the  heads,  some  of 
the  oxide  coating  on  the  tape  will  be  transferred  to  the  heads  during  normal 
operation.  To  assure  proper  operation  of  the  Datassette,  it  is  necessary  to 
clean  this  oxide  film  from  the  heads  periodically  using  a  cotton  swab  soaked 
in  denatured  alcohol.  Clean  both  heads,  the  capstan,  and  the  pinch  roller. 
Allow  the  area  to  dry  completely  before  closing  the  cover. 

The  process  of  reading  and  writing  onto  a  magnetic  surface,  such  as  a 
cassette  tape,  results  in  the  build-up  of  residual  magnetism  on  the  heads  of  the 
cassette  recorder.  Because  of  this  build-up,  it  is  a  good  idea  to  demagnetize 
the  heads  each  time  you  clean  them.  Skipping  this  step  in  your  regular 
maintenance  may  eventually  result  in  sufficient  loss  of  fidelity  to  cause  both 
read  and  write  errors  in  your  programs. 

To  demagnetize  the  heads,  you  will  need  a  tape  head  demagnetizer,  such 
as  the  one  in  Figure  1-9.  This  is  an  inexpensive  unit  that  can  be  purchased  at 
most  audio  equipment  stores. 

The  Datassette  should  be  OFF  when  you  are  demagnetizing  the  tape 
heads.  Open  the  cassette  drive  door  and  press  the  PLAY  key.  Make  sure  the 
demagnetizer  is  at  least  two  feet  away  from  the  Datassette  before  plugging  it 


FIGURE  1-9.  A  typical  tape  head  demagnetizer 
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in.  Plug  in  the  demagnetizer  and  slowly  move  it  toward  the  Datassette  until  it 
touches  one  of  the  heads.  Gently  move  it  around  on  one  head  surface  and  then 
on  the  other.  Next,  touch  all  the  metal  surfaces  near  the  heads  and  slowly 
move  back  away  from  the  Datassette.  When  you  are  at  least  two  feet  away, 
unplug  the  demagnetizer. 

Care  of  Cassette  Tapes 

When  you  use  a  new  tape,  balance  the  tension  on  the  tape  by  fast  forwarding  it 
to  the  end  and  then  rewinding  it  to  the  beginning.  This  will  help  prevent  load 
errors. 

Buy  short  tapes,  15  to  30  minutes  at  most.  This  will  not  only  reduce  your 
search  time  when  running  programs  from  the  middle  of  your  tapes,  but  will 
ensure  that  you  are  using  thicker  and  stronger  tapes  that  are  less  likely  to 
stretch  or  break  with  use.  Stay  away  from  bargain  brands;  they  tend  to  cause 
load  errors  more  often  than  high-quality,  low-noise  tapes. 

Store  your  cassettes  in  a  cool,  dry  place,  away  from  any  magnetism. 

NOTE:  One  of  the  most  hazardous  places  to  store  tapes  is  on  or  near 
your  television,  which  produces  a  magnetic  field  strong  enough  to  alter  the 
data  they  contain.  Never  touch  the  oxide  coating  on  the  tape  itself;  the  surface 
is  easily  scratched  and  can  be  damaged  by  the  oils  on  your  hands. 

Cassette  Tape  Write-Protect 

You  can  avoid  recording  (writing)  over  programs  you  want  to  save  by  write- 
protecting  them.  Look  at  Figure  1-8;  each  cassette  tape  has  two  write-protect 
tabs,  one  tab  for  each  side  of  the  tape.  Breaking  out  a  tab  locks  out  the  REC 
(Record)  key  on  the  Datassette.  Should  you  decide,  after  breaking  out  a 
write-protect  tab,  that  you  do  want  to  record  a  program  on  that  side  of  a  tape, 
simply  put  a  piece  of  tape  over  the  write-protect  opening. 


DISK  DRIVES 

The  C-128  can  use  the  model  1571  (Figure  1-10)  or  1541  disk  drive,  which  has 
been  designed  to  interface  directly  with  the  C-128  through  its  serial  port. 
Table  1-3  shows  the  specifications  for  the  1571  disk  drive. 

The  1571  disk  drive  can  store  from  174,848  to  409,600  bytes  of  data  per 
diskette,  depending  on  the  disk  format. 
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FIGURE  1-10.  The  Commodore  1571  disk  drive 


Connecting  Disk  Drives 

To  connect  a  disk  drive  to  the  C-128  computer,  follow  these  steps: 

1.  Unplug  the  computer's  power  cord  from  the  electrical  outlet. 

2.  Connect  the  interface  cable  supplied  with  the  disk  drive  to  the  serial 
port  on  the  back  of  the  C-128. 

3.  Plug  the  disk  drive's  power  cord  into  an  AC  outlet. 

4.  Plug  the  C-I28's  power  cord  into  an  AC  outlet. 

5.  Check  all  your  connections.  If  they  look  good,  then  proceed  to  the 
power-on  test. 

Power-On  Test 

To  perform  a  power-on  test,  follow  these  steps: 

1.  Turn  the  C-I28's  power  ON.  Wait  until  it  has  completed  its  initial- 
ization. 

2.  Open  the  disk  drive  door  and  make  sure  the  drive  is  empty. 

3.  Turn  the  disk  drive's  power  ON. 
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TABLf  1-3.  1571  Disk  Drive  Specifications 


Storage: 

Total  disk  capacity 

174,848-409,600  bytes  per  diskette 

Number  of  program  names 

144  per  diskette 

Sectors  per  track 

1  f-Zl 

Rvtf*^  npr  QPPtnr 

198          SI?  1094 

1Z,0,  ^JU,  ll/ZH 

Number  of  tracks 

35  70  80 

Numbpr  nf  sprtnrs 

400-9080 

Disk  Memory 

4016 

2K  RAM 

23256 

32K  ROM 

Mechanical 

specifications: 

Dimensions 

Height 

76  mm 

Width 

216  mm 

Depth 

346  mm 

Electronic 

specifications: 

Power  requirements 

Voltage 

100,  120,  220,  or  240  V  AC 

Frequency 

50  or  60  Hz 

Power 

25  watts 

Media: 

Diskettes 

Standard  mini  5  1/4,  single-sided,  single- 
density/ double  density,  double-sided 

Indicator  Lights 

The  1571  disk  drive  has  two  indicator  lights  on  its  front  panel.  The  green  one 
will  glow  when  power  is  supplied  to  the  unit.  The  red  one  is  the  disk  activity 
indicator.  It  will  glow  when  the  drive  is  running  and  flash  if  there  is  an  error 
condition. 

Loading  and  Unloading  Diskettes 

Figure  1-11  illustrates  the  various  parts  of  a  floppy  diskette.  The  magnetic 
surface  itself  is  a  disk  made  of  a  thin,  flexible  plastic  similar  to  the  material 
used  in  cassette  tapes.  This  fragile  disk  is  enclosed  in  a  protective  jacket.  The 
jacket  is  then  placed  in  an  envelope  that  protects  the  read/ write  slot. 
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Read/ write  slot 


\L9\ 

3JOpOUIUI03 


Protective  jacket , 
Hard /soft-sectored  hole. 


Write-protect  notch;  . 
when  covered,  diskette 
contents  cannot  be  altered 


FIGURE  1-11.  Floppy  diskette 


As  mentioned  earlier,  the  1571  disk  drive  puts  more  data  onto  a  single 
diskette  than  almost  any  other  disk  drive.  The  way  it  does  this  is  by  putting 
more  blocks  of  data  (sectors)  into  the  data  tracks  that  are  near  the  outside  of 
the  diskette.  Some  disk  drives  put  the  same  number  of  sectors  on  each  track. 
Of  those  that  do  this,  there  are  some  that  use  hard-sectored  diskettes.  These 
diskettes  have  a  series  of  evenly  spaced  holes  near  their  center.  The  disk  drive 
uses  these  holes  to  position  the  sectors.  Since  the  1571  does  not  have  regularly 
spaced  sectors,  it  does  not  use  these  holes.  The  1571  uses  only  soft-sectored 
diskettes  (those  with  only  one  hole  in  them). 

To  determine  what  kind  of  diskette  you  have,  follow  this  procedure  (see 
Figure  I  - 12): 

1 .  Take  the  diskette  out  of  its  envelope  (not  the  jacket),  and  hold  it  by  its 
edges. 

2.  Gently  insert  two  fingers  into  the  center  hole. 

3.  Rotate  the  diskette  with  the  two  fingers  in  the  center  hole  until  a  small 
hole  in  the  diskette  aligns  with  the  outer  small  hole  in  the  jacket. 

4.  Continue  rotating  the  diskette  inside  the  jacket.  If  you  find  only  one 
hole,  the  diskette  is  soft-sectored.  If  you  find  more  than  one  hole,  it  is 
hard-sectored  and  cannot  be  used  with  the  1571  disk  drive. 
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FIGURE  1-12.  Test  for  soft-sectored  diskette 


Loading  the  Drive 

Perform  the  following  steps  to  load  the  1571  disk  drive: 

1.  Make  sure  the  disk  drive  is  OFF  (the  red  activity  light  is  not  lit). 

2.  Hold  the  diskette  by  its  jacket.  Do  not  touch  the  exposed  sections  of 
the  diskette!  The  diskette's  label  should  be  facing  up,  with  the  write- 
protect  notch  (Figure  1-11)  on  your  left. 

3.  Carefully  slide  the  diskette  into  the  front  slot  until  it  stops.  If  it  doesn't 
slide  in  smoothly,  pull  it  out  and  try  again.  Forcing  it  can  damage 
both  the  diskette  and  the  drive. 

4.  With  two  fingers,  rotate  the  latch  until  it  locks  down. 

Unloading  the  Drive 

To  unload  the  1571  disk  drive,  follow  these  steps: 

1.  Make  sure  the  disk  drive  is  OFF  (the  red  activity  light  is  not  lit). 

2.  Using  two  fingers,  rotate  the  latch  to  release  it. 

3.  Hold  the  diskette  gently  with  your  thumb  and  forefinger,  and 
withdraw  it  from  the  drive.  Do  not  bend  or  force  the  diskette! 

4.  Put  the  diskette  back  into  its  envelope. 
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FLOPPY  DISKS 

If  handled  properly,  floppy  diskettes  are  a  convenient  medium  for  storing 
data.  They  are,  however,  quite  fragile,  and  it  is  just  as  easy  to  write  over 
important  data  as  it  is  to  write  it  in  the  first  place. 

Care  of  Diskettes 

Diskettes  must  be  handled  with  care.  All  of  your  information  will  be  stored  on 
them  and,  once  a  diskette  is  damaged,  it  is  virtually  impossible  to  retrieve  this 
information.  Here  are  some  hints  that  will  help  you  protect  your  diskettes. 

1 .  Whenever  the  diskette  is  out  of  the  disk  drive,  place  it  in  its  protective 
envelope. 

2.  Never  remove  a  diskette  from  its  protective  jacket! 

3.  When  you  label  your  diskettes,  use  only  a  felt-tip  pen.  Pencils  or 
ball-point  pens  may  damage  the  diskette. 

4.  Do  not  touch  or  try  to  clean  the  diskette  surface.  This  will  damage  it. 

5.  Do  not  smoke  while  using  diskettes.  Tobacco  ash  or  smoke  residue 
will  damage  the  diskette  surface. 

6.  Keep  diskettes  away  from  all  magnetic  fields!  Even  placing  them  on 
top  of  your  television  set  or  disk  drive  can  cause  some  distortion  of 
the  data  stored  on  the  diskette. 

7.  Do  not  expose  your  diskettes  to  heat  or  sunlight. 

Diskette  Write-Protection 

You  can  prevent  the  information  on  your  diskettes  from  being  overwritten  by 
write-protecting  them.  To  do  this,  simply  cover  the  write-protect  notch 
(Figure  1-11)  with  the  adhesive  labels  that  came  with  your  diskettes,  or  with  a 
piece  of  opaque  tape. 

If  you  remove  the  write-protect  notch  cover,  you  will  be  able  to  write  to 
the  diskette  again. 


THE  MPS  803  GRAPHIC  PRINTER 

While  you  can  use  almost  any  printer  with  the  C-128  through  the  parallel  port 
or  by  installing  an  IEEE  488  interface,  the  MPS  803  Graphic  Printer  operates 
directly  with  the  C-128  (Figure  1-13).  The  MPS  803  can  print  any  standard 
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FIGURE  1-1 3.  Model  MPS  803  Graphic  Printer 


C-128  character  or  symbol,  both  normal  and  reversed,  and  it  can  be  pro- 
grammed to  print  dot  graphics. 

The  MPS  803  prints  characters  using  a  7  X  5  dot  matrix  and  a  7  X  6  dot 
matrix  for  special  symbols.  Table  1-4  shows  the  specifications  for  the  MPS 
803  Graphic  Printer. 

Connecting  the  Printer 

Follow  these  steps  to  connect  the  MPS  803  Graphic  Printer  to  the  C-128: 

1.  Unplug  the  computer's  power  cord  from  the  electrical  outlet. 

2.  Look  at  the  back  of  the  C-128.  There  are  two  round,  similar 
connectors  in  the  center  of  the  back.  The  one  with  five  pins  is  the 
video  port.  The  other  connector  has  six  pins.  It  is  the  serial  port.  Plug 
the  printer  cable  into  the  serial  port. 
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TABLE  1-4.  MPS  803  Printer  Specifications 


1.  General  Specifications 

A. 

Print  head  

.  .  .7X6  dot  matrix  impact  dot  matrix  print 

B. 

Character  set  

Upper-  and  lowercase  characters,  numerals,  symbols, 

and  C-128  graphic  characters 

C 

...  7  dots  per  column 

D. 

C-128  8-bit  code 

E. 

.  60  characters  per  sec 

F. 

Maximum  line  width. . . 

. .  .80  columns 

G. 

Character  spacing  

. .  10  characters  per  in. 

H. 

Linefeed  spacing  

.  .6  dots  Character  mode 

8  dots  Graphic  mode 

5.6  linefeeds/ sec. .  .  .Graphic  mode 

I. 

Paper  width  

. .  .4  to  10  in.  acceptable 

J. 

. .  .(Maximum)  Original  plus  2  copies 

K. 

.  . .  Built-in  cassette  type 

L. 

Physical  specifications . . 

190DX330WX70H 

M. 

Weight  .  

. . .  Approximately  2.0  kg 

2.  Electrical  Specifications 

A. 

Power  

120  V  AC 

15  watts  max 

3.  The  other  end  of  the  cable  plugs  into  the  six-pin  plug  on  the  back  of 

the  MPS  803  printer. 

4.  Turn  the  C-128  ON  and  wait  for  it  to  initialize  (the  READY  display 

will  appear  on  the  screen). 

5.  Turn  on  the  MPS  803  Graphic  Printer.  The  red  power  light  on  the  top 
of  the  printer  should  glow,  and  the  print  head  should  travel  to  the 
center  of  the  carriage  and  return  to  the  left. 

6.  To  run  the  diagnostic  test,  turn  the  printer  OFF,  then  press  (and  hold) 
the  Paper  Advance  button  while  you  turn  power  ON.  The  printer 
should  begin  printing  the  entire  C-128  character  set. 

The  printer  should  continue  printing  this  until  you  turn  the  power 

OFF. 
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If  the  printer  does  not  operate  as  described,  recheck  all  your  connections 
and  repeat  procedure.  If  you  are  still  unsuccessful,  consult  your  Commodore 
dealer. 

Installing  the  Ribbon 

Perform  the  following  steps  to  install  the  printer  ribbon: 

1.  Lift  up  the  clear  plastic  sound  cover  (Figure  1-14). 

2.  Make  sure  that  the  ribbon  is  not  twisted  (as  shown  in  Figure  1-15); 
then  tilt  the  ribbon  cassette  into  the  machine  and  press  it  down  into 
position. 

3.  Slide  the  ribbon  guide  all  the  way  over  to  the  right  until  it  snaps  into 
position. 


Top  Cover 


FIGURE  1  -14.  Lifting  the  top  cover  of  the  MPS  803  printer 
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FIGURE  1  -15.  Ribbon  cassette 


4.  Replace  the  clear  sound  cover. 

To  remove  a  ribbon,  simply  reverse  this  procedure. 

Paper  Insertion 

The  MPS  803  Graphic  Printer  uses  a  continuous  form  that  can  be  from  4  to  10 
inches  wide.  It  is  sprocketed  on  both  sides  and  can  have  as  many  as  three  parts 
(one  original  and  two  copies)  as  long  as  the  total  thickness  does  not  exceed  0.2 
mm. 

Follow  these  steps  to  insert  paper  into  the  MPS  803  Graphic  Printer: 

1.  Turn  the  printer  OFF  and  unplug  its  power  cord. 

2.  Slide  the  paper  release  lever  toward  the  rear  of  the  printer. 

3.  Insert  the  paper  from  the  rear  of  the  printer  through  the  paper  chute. 
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4.  Continue  feeding  the  paper  by  hand  until  it  emerges  at  the  front  of  the 
printer. 

5.  Slide  the  paper  release  lever  back  toward  the  front  of  the  printer  to 
close  it. 

6.  Advance  the  paper  using  the  knob,  making  sure  the  paper  moves 
smoothly  through  the  feed  mechanism. 

7.  Plug  in  the  printer  and  turn  it  ON. 


CHAPTER 


Operating  4% 

TheC-128  ^ 


This  chapter  will  introduce  you  to  the  basic  operation  of  the  C-128  and  some 
of  its  peripheral  devices:  the  Datassette,  the  1571  disk  drive,  and  the  MPS 
803  printer.  It  will  also  help  you  become  familiar  with  the  C-128's  keyboard 
and  display  and  with  the  computer's  two  modes  of  operation:  immediate  and 
program  modes. 

Before  continuing,  you  should  be  aware  of  one  aspect  of  the  C-128.  As 
you  may  already  know,  the  C-128  is  actually  three  computers  in  one:  a  C-64,  a 
C-128,  and  a  CP/M  computer.  In  this  chapter,  the  details  that  are  covered 
apply  to  both  C-64  mode  and  C-128  mode.  If  you  have  an  RGB  monitor, 
depress  the  40/80  Display  switch  on  the  keyboard  before  you  turn  the 
computer  ON.  This  will  put  you  into  C-128  mode  with  an  80-column  display. 
If  you  are  using  a  composite  monitor  or  a  television,  leave  the  40/80  Display 
switch  in  the  upper  position. 

To  switch  from  C-128  mode  to  C-64  mode,  type 

GO  64 

The  computer  will  ask,  ARE  YOU  SURE?  Type  Y  and  press  RETURN  to  enter 
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C-64  mode.  (Note  that  this  is  a  one-way  street:  to  switch  back,  youll  need  to 
turn  the  computer  OFF  and  then  ON  again.)  For  the  purposes  of  this  chapter, 
however,  you  may  remain  in  C-128  mode. 

IMMEDIATE  MODE 

When  you  turn  on  the  C-128,  it  is  operating  in  immediate  mode.  The  flashing 
cursor  signifies  that  the  computer  is  waiting  for  instructions  and  shows  where 
the  next  character  you  type  on  the  keyboard  will  appear  on  the  screen. 

In  immediate  mode,  you  can  use  the  C-128  as  you  would  a  calculator.  You 
enter  statements  —  instructions  to  display  information,  perform  a  calcula- 
tion, or  carry  out  some  other  function.  When  you  enter  a  statement  and  press 
the  RETURN  key,  the  C-128  processes,  or  executes,  the  statement.  First, 
though,  the  C-128  checks  your  entry  for  syntax — the  correct  combination  of 
characters  in  a  statement.  If  the  syntax  is  correct,  the  statement  executes.  If  it 
isn't  correct,  the  following  message  appears: 

9SVNTRX  ERROR 

READY. 

■ 

If  you  get  a  syntax  error  message,  check  your  statement  for  typographi- 
cal errors. 

Immediate  mode  does  what  its  name  implies:  any  statements  you  enter 
will  execute  immediately  after  you  press  RETURN. 

The  PRINT  statement  is  the  most  frequently  used  immediate  mode 
statement.  PRINT  instructs  the  C-128  to  display  whatever  follows  it.  For 
example,  PRINT  will  display  the  results  of  calculations,  such  as 

PRINT  360+199+1000 

which,  in  this  case,  would  be  1559. 

PRINT  will  also  display  characters  or  entire  strings  of  characters.  A 
string  is  a  sequence  of  characters  that  can  include  letters,  numbers,  spaces, 
and  symbols.  To  display  a  string  such  as 

AND  MILES  TO  GO  BEFORE  I  SLEEP 

on  the  C-128's  screen,  you  would  type  the  following  immediate  mode  state- 
ment and  press  RETURN: 

-    PR I NT "AND  MILES  TO  GO  BEFORE  I  SLEEP" 
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The  string  has  quotation  marks  around  it;  anything  enclosed  in  quotation 
marks  in  a  PRINT  statement  will  display  literally  as  a  string  of  characters. 
For  example,  a  PRINT  statement  such  as 

PR I NT" 366+ 199+ 1000" 

will  not  calculate  anything.  The  computer  will  display  a  string  of  characters, 
which  in  this  case  is  three  numbers  connected  by  plus  signs.  Conversely,  the 
statement 

PRINT  AND  MILES  TO  GO  BEFORE  I  SLEEP 

will  not  display  anything  except  a  syntax  error  message.  The  syntax  of  a 
PRINT  statement  always  expects  numeric  or  string  information  to  follow. 
The  word  AND  does  not  represent  a  number  and  is  not  in  quotes;  therefore, 
the  C-128  rejects  the  statement. 

You  can  abbreviate  PRINT  by  using  a  question  mark.  The  following 
statements 

PRINT"GODFREV  CAMBRIDGE" 

and 

?" GODFREY  CAMBRIDGE" 
produce  the  same  result. 

Screen  Editing 

One  of  the  most  powerful  features  of  the  C-128  is  its  screen  editor.  The  key  to 
using  the  C-128's  editing  capabilities  is  the  cursor.  You  can  move  the  cursor  in 
four  directions:  up,  down,  left,  and  right.  You  can  also  insert  or  delete 
characters  anywhere  on  the  screen,  or  even  clear  the  entire  screen  with  a  single 
keystroke. 

EDITING  TEXT  ON  THE  CURRENT  DISPLAY  LINE 

Occasionally,  you  may  notice  a  mistake  on  a  line  you  are  currently 
entering.  You  can  correct  mistakes  on  a  line  you  are  entering  by  backspacing 
to  the  error  and  correcting  it.  For  example, 

OUR  BUDGEY 

was  intended  to  display  as  OUR  BUDGET.  You  can  change  the  Y  to  a  T  easily 
enough.  Type  in  OUR  BUDGET  and  use  the  SHIFT  and  CRSR  LEFT/ RIGHT 
keys  to  position  the  cursor  over  the  Y. 
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OUR  BUDGEfl 
OUR  BUDGET 

To  change  the  Y  to  a  T,  simply  type  T.  This  replaces  the  old  letter  and 
moves  the  cursor  one  position  to  the  right. 

BACKSPACING  WITH  THE  DELETE  KEY 

If  you  just  entered  a  character  that  you  would  like  to  retype,  press  the 
INS /DEL  key  to  remove  the  incorrect  character  and  then  continue  typing. 
When  you  used  the  CRSR  LEFT/  RIGHT  key,  the  cursor  simply  moved  over  the 
characters  on  the  screen  without  changing  them.  Try  the  following  example 
using  the  INS/ DEL  key: 

OUR  BUDGE! 
OUR  BUDGET! 

SHIFTING  AND  DELETING  TEXT  WITH  THE  DELETE  KEY 

In  the  following  example,  the  word  BUDGET  has  been  entered  with  two 
U's.  It  will  be  necessary  to  delete  one  of  the  LPs  and  move  the  text  to  the  left  to 
close  up  the  extra  space  left  by  the  U. 

To  do  this,  use  the  CRSR  LEFT/  RIGHT  key  to  position  the  cursor  over  the 
D  and  press  the  INS  /  DEL  key  once.  This  key  erases  the  letter  to  the  left  of  the 
cursor,  deleting  the  U  and  shifting  the  text  to  fill  the  space. 

OUR  BUJJDGET 

OUR  BUDGET 

SHIFTING  TEXT  TO  INSERT 
CHARACTERS 

In  this  example,  you  will  need  to  change  OUR  BUDGET  to  OUR 
FAMILY  BUDGET.  To  do  this,  use  the  CRSR  LEFT/  RIGHT  key  to  position  the 
cursor  over  the  space  between  OUR  and  BUDGET. 

FAMILY  has  six  letters;  you  will  also  need  a  space  at  the  end  of  the  word. 
Hold  down  the  SHIFT  key  and  press  INS/ DEL  seven  times.  This  will  produce 
seven  spaces  between  the  two  words.  You  may  now  type  FAMILY  between 
OUR  and  BUDGET. 

Remember,  when  you  are  inserting  characters,  the  character  directly 
under  the  cursor  is  the  one  that  will  be  shifted  to  the  right.  You  must  also 
remember  to  enter  enough  spaces  for  each  word  you  add,  plus  a  space 
between  each  word. 
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OURBBUDGET 

0UR1  BUDGET 

OUR  FRMILVBBUDGET 

EDITING  TEXT 

BETWEEN  QUOTATION  MARKS 

If  you  are  editing  text  enclosed  in  quotation  marks,  you  will  need  to  take 
certain  precautions  because  anything  entered  within  a  string  will  be  incorpo- 
rated into  it  (except  quotation  marks,  RETURN,  and  RUN/ STOP).  This  quote 
mode  enables  you  to  enter  special  characters,  but  it  can  be  frustrating  when 
you  merely  want  to  fix  an  error  in  a  statement.  For  example,  the  following  line 
should  say  PRINT  "HOT  DOGS  FOR  SALE".  Enter  the  line  exactly  as 
shown;  do  not  type  end  quotes  or  press  RETURN.  Then  try  to  make  the 
necessary  change  to  HOYT. 

PRINT  "HOVT  DOGS  FOR  SALE 

When  you  tried  to  backspace  to  correct  HOYT,  the  computer  printed  a 
reverse  vertical  bar.  To  backspace  when  editing  text  in  quotation  marks,  you 
will  need  to  exit  the  quote  mode.  One  way  to  do  this  is  to  type  another  set  of 
quotes.  While  you  must  enter  quote  mode  to  enter  a  string,  you  must  exit 
quote  mode  to  edit  the  string. 

Another  way  to  escape  from  the  quote  mode  is  to  hold  SHIFT  down  and 
press  RETURN.  This  will  move  the  cursor  down  one  line,  allowing  you  to  move 
the  cursor  up  and  make  any  changes  you  like. 

While  this  may  seem  to  be  an  unwelcome  "feature,"  you  can  write 
programs  using  cursor  keys.  For  instance,  the  immediate  mode  statement 

HELLO  DOWN  THERE 

PRINT  "TTHELLO  DOWN  THERE" 

displays  the  text  above  the  PRINT  statement  instead  of  below  it,  as  would 
normally  be  the  case. 

Arithmetic  Calculations 

The  C-128  can  perform  the  four  standard  mathematical  operations:  addition, 
subtraction,  multiplication,  and  division.  The  symbols  for  addition  and 
subtraction  are  the  familiar  plus  sign  and  minus  sign,  but  an  asterisk  is  used 
for  multiplication  and  a  slash  for  division.  Therefore,  to  multiply  4  by  4,  you 
would  enter 

PRINT  4*4 
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?4*4 

To  divide  8  by  2  you  would  enter 
PRINT  8/2 

or 

?8/2 

PROGRAM  MODE 

In  both  immediate  mode  and  program  mode,  you  enter  statements  and  the 
computer  responds  to  them.  However,  immediate  mode  statements  are  very 
limited.  If  you  were  to  press  the  CLR  SCREEN  key,  your  statement  would 
disappear. 

The  immediate  mode  examples  you  entered  earlier  in  this  chapter  were 
simple,  one-line  programs,  and  they  do  not  do  much.  Once  you  become 
familiar  with  your  computer,  you  will  want  to  write  longer  programs.  BASIC 
programs  can  be  hundreds  of  statements  long;  you  will  not  want  to  enter  them 
in  immediate  mode.  Instead,  you  will  write  programs  in  program  mode, 
which  stores  statements  in  main  memory.  Another  advantage  of  program 
mode  is  that  the  statements  execute  "under  their  own  power."  In  immediate 
mode,  the  computer  executes  one  statement  and  then  waits  for  you  to  key  in 
another  statement.  In  program  mode,  statements  execute  automatically  in  an 
order  you  specify. 

Program  Entry 

Programs  may  be  entered  via  the  keyboard  or  they  may  be  loaded  into 
memory  with  the  Datassette  or  disk  drive.  Each  statement  entered  through 
the  keyboard  has  a  corresponding  line  number.  When  you  press  RETURN  at 
the  end  of  each  statement,  that  line  is  stored  in  the  C-128's  memory. 

You  can  use  any  line  numbers  between  0  and  63999.  When  you  enter  lines 
in  your  programs,  they  will  execute  in  the  order  they  are  numbered,  not  the 
order  in  which  they  are  entered.  For  instance,  if  you  entered  the  lines 

100  PRINT  "CRHMBEN ! " 

90  PRINT  "RRLPH" 

75  PRINT  "THE  WINNER  IS" 

they  would  execute  in  the  following  order: 
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THE  WINNER  IS 
RRLPH 
CRRMDEN ! 


It  doesn't  matter  that  there  are  gaps  between  the  numbers  used;  C-128  BASIC 
keeps  the  line  numbers  in  order  as  you  enter  them.  In  fact,  you  should  number 
statements  by  some  increment,  such  as  fives,  tens,  or  hundreds,  so  you  can 
later  add  statements.  All  of  this  will  be  covered  in  greater  detail  in  Chapter  3. 


Running  a  Program 

The  RUN  statement  causes  the  computer  to  execute  any  program  in  memory. 
Enter  the  following  program: 

10  PRINT  X 
20  X=X+1 
30  GOTO  10 


The  GOTO  at  line  30  tells  the  computer  to  return  to  line  10  and  execute  the 
instruction  there. 

Typing  RUN  begins  execution  at  the  lowest  line  number  in  your 
program. 

RUN 

0 

1 

2 

3 

4 

5 

S 
7 
8 
9 

10 
11 
12 
13 
14 
15 
16 
17 
18 
19 
20 
21 


RUN  followed  by  a  line  number  starts  execution  of  your  program  at  the 
specified  line  number. 
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RUN  20 
1 
2 
3 
4 
5 
6 
7 
8 
9 
10 
11 
12 
13 
14 
15 
16 
17 
18 
19 
20 
21 


USING  THE  DATASSETTE 

The  Datassette  saves  you  the  time  and  tedium  of  keying  in  programs  over  and 
over  again.  The  Datassette  will  store  BASIC  programs  and  retrieve  them  at 
your  request. 

The  operations  the  Datassette  will  perform  go  well  beyond  the  scope  of 
this  chapter.  Chapter  8  explores  the  full  potential  of  the  Datassette  for  storing 
and  retrieving  data. 

Saving  a  Program 

Make  sure  the  short  program  you  entered  in  the  last  section  is  still  in  memory 
by  typing  LIST.  If  it  isn't,  reenter  it.  To  save  it  on  a  cassette,  type 

SAVE 11  RALPH" 

The  C-1 28  will  respond  with 

PRESS  RECORD  &  PLflV  ON  TAPE 

Press  PLAY  and  RECORD  simultaneously.  If  you  press  just  the  PLAY  key, 
the  C-128  will  send  data  to  the  Datassette  but  nothing  will  be  stored  on  tape. 
After  you  press  PLAY  and  RECORD,  the  C-128  will  respond  with 

OK 

SAVING  RALPH 
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While  the  C-128  is  saving  the  program  on  the  Datassette,  the  cursor 
disappears.  When  it  is  finished,  the  Datassette  will  stop,  the  C-128  will  display 
the  READY  message,  and  the  flashing  cursor  will  return. 

Verification 

After  you  save  a  program  on  the  Datassette,  it  is  a  good  idea  to  verify  that  it 
was  properly  recorded.  Occasionally,  poor-quality  tapes  or  slight  mechanical 
fluctuations  may  cause  a  program  to  be  incorrectly  recorded.  To  protect 
yourself  from  losing  programs,  always  verify  them  immediately  after  you 
store  them. 

To  verify  a  program,  follow  these  steps: 

1.  Rewind  the  tape  and  press  the  STOP/ EJECT  key. 

2.  Type  VERIFY,  followed  by  the  program's  name,  and  press  RETURN. 

A  typical  verify  dialog  with  the  C-128  may  look  like  the  following: 

VERIFV  " RALPH" 

PRESS  PLAV  ON  TAPE 
OK 

SEARCHING  FOR  RALPH 
FOUND  RALPH 

VERIFV I NO 
OK 

RE ADV. 

If  the  program  was  not  saved  properly,  you  will  get  an  error  message.  If 
this  happens,  you  should  SAVE  it  again  and  reverify  it. 

Loading  a  Program 

To  load  a  program  from  the  Datassette,  simply  type  LOAD  program  name. 
The  C-128  will  respond  by  displaying 

PRESS  PLflV  ON  TAPE 

After  you  press  the  PLAY  key,  the  C-128  will  display  OK  and  then 
SEARCHING  FOR 

When  you  load  a  program  from  the  Datassette,  you  do  not  need  to  enter 
a  program  name.  If  you  simply  type  LOAD,  the  computer  will  load  the  first 
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program  it  reaches  on  the  tape.  Using  a  program  name  causes  the  computer  to 
look  for  the  file  named,  skipping  any  others  it  finds. 

After  a  program  is  loaded  from  tape,  you  can  leave  the  PLAY  key 
depressed  if  you  will  be  loading  more  information  from  the  tape  at  a  later 
time.  However,  if  you  do  not  intend  to  load  another  program  from  tape  soon, 
it  is  a  good  idea  to  press  STOP  to  release  the  PLAY  key  so  you  will  not 
accidentally  try  to  SAVE  a  program  while  the  Datassette  is  in  the  play  mode. 
The  C-128  can  detect  when  a  Datassette  key  has  been  pressed,  but  it  cannot 
distinguish  which  key  was  pressed.  Therefore,  if  PLAY  and  RECORD  are 
pressed  (to  SAVE  a  program)  and  you  attempt  to  LOAD,  the  Datassette  will 
erase  the  program  instead  of  reading  it. 

You  may  occasionally  have  trouble  loading  a  program  from  tape.  Instead 
of  displaying 

REflDV. 

the  C-128  may  display  the  following  message: 

?LOflB 
ERROR 
REflDV. 
■ 

If  this  happens,  rewind  the  tape  and  try  loading  it  again.  Try  this  several  times 
if  necessary.  If  this  does  not  work,  there  may  have  been  an  undetected 
problem  when  the  program  was  saved.  Always  VERIFY  programs  after  you 
SAVE  them,  and  if  they  are  important  or  have  taken  considerable  time  to 
enter,  make  one  or  more  backup  copies. 

One  way  to  reduce  errors  during  the  SAVE  procedure  is  to  fast-forward  a 
new  tape  to  the  end  and  then  rewind  it  to  the  beginning  before  storing 
anything  on  it.  This  winding  and  rewinding  process  will  tend  to  make  the  tape 
move  through  the  tape  mechanism  more  smoothly  because,  when  tapes  are 
manufactured,  they  are  wound  onto  their  spools  at  high  speed.  This  process 
often  puts  some  tension  on  the  tape,  and  when  it  is  first  unwound,  it  may  jump 
a  bit  as  it  moves  through  the  mechanism.  It  may  also  pull  and  stick  slightly  in 
the  cassette.  Although  these  effects  are  not  usually  noticeable  in  audio  appli- 
cations, they  can  cause  data  errors  on  computer  tapes. 

Before  entering  a  LOAD  instruction,  be  sure  to  rewind  the  tape  to  a 
point  before  your  program  begins;  otherwise  the  C-128  will  never  find  it.  A 
good  practice  is  to  note  the  number  of  the  tape  counter  at  the  beginning  of 
your  program  and  write  it  down  on  the  tape  label  beside  the  name  of  the 
program.  This  will  also  save  time  when  you  LOAD  programs,  since  the 
computer  will  not  need  to  go  through  as  much  tape  before  reaching  the 
program  you  want. 
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LOAD  and  RUN 

Pressing  SHIFT  and  RUN/ STOP  together  will  automatically  LOAD  and  RUN 
the  next  program  on  the  Datassette.  This  works  only  when  the  computer  is  in 
immediate  mode  (not  executing  an  instruction  from  within  a  program). 

OPERATING  THE  1571  DISK  DRIVE 

If  you  are  using  a  cassette  drive,  you  will  save  considerable  time  because  you 
don't  have  to  enter  programs  by  hand  whenever  you  want  to  run  them.  The 
1571  disk  drive  can  save  you  even  more  time  because  of  its  much  greater 
flexibility  and  faster  data  access  time.  This  section  will  discuss  the  basic 
operation  of  the  disk  drive,  how  to  list  the  diskette  directory,  and  how  to  load 
and  run  programs  from  a  diskette.  The  disk  operations  and  statements  will  be 
covered  in  detail  in  Chapter  7. 

Loading  a  Program 

To  load  a  program  from  a  diskette  in  the  1571  disk  drive,  type  LOAD  "file 
name",8.  The  "8"  is  the  device  number  of  the  disk  drive.  This  device  number  is 
set  at  the  factory.  The  C-128  will  display  SEARCHING  FOR  "file  name".  The 
disk  drive  will  activate,  and  the  red  light  on  the  front  of  the  drive  will  come  on. 
If  the  program  is  on  the  diskette,  the  C-128  will  also  display 

LOADING 
REflDV. 

If  not,  you  will  see 

?FILE  NOT  FOUND 
ERROR 

READY. 

If  you  don't  know  the  exact  name  of  a  particular  file  or  what  is  on  your 
diskette,  type 

L0flD"*%8 

and  the  disk  directory  will  be  loaded  into  memory.  To  display  the  directory, 
type 

LIST 

and  the  directory  will  appear  on  the  screen. 
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e  uraEfBOijj 


5 

"UNIVERSAL  WEDGE" 

PRG 

8 

"UNIT  TO  UNIT" 

PRG 

o 

unniNUt  iu*ri 

11 

"COPV  1540-1541" 

PRG 

27 

"PRINTER  DEMO" 

PRG 

12 

" SEQUENT IRL" 

PRG 

11 

"PERFORMANCE  TEST" 

PRG 

5 

"CHECK  DISK" 

PRG 

17 
■ 

"LOGIC  DIAGNOSTIC" 

PRG 

To  recall  any  program  from  diskette,  you  must  enter  the  file  name 
exactly  as  it  is  listed  in  the  directory.  Therefore,  it  is  generally  helpful  to  list  the 
disk  directory  before  loading  any  programs. 

Look  at  the  directory  in  the  previous  display.  The  top  row  (in  reverse 
letters)  shows  the  name  of  the  diskette  and  its  ID  number.  The  disk  drive 
always  stores  this  number,  and  each  time  a  diskette  is  accessed,  it  compares 
the  ID  number  with  the  number  it  has  stored  from  the  last  disk  operation.  If 
the  numbers  are  the  same,  the  disk  drive  assumes  that  the  same  diskette  is 
being  accessed  and  simply  performs  its  operation  (SAVE  or  LOAD).  If  the 
number  on  the  diskette  does  not  match  the  one  in  the  disk  drive's  memory,  the 
disk  drive  will  create  a  map  of  all  the  files  on  the  diskette  and  update  its  ID 
memory.  This  process  is  called  initialization. 

As  long  as  no  two  diskettes  have  the  same  ID  number,  the  disk  drive  will 
always  initialize  itself  automatically  when  you  change  diskettes.  If  two 
diskettes  have  the  same  ID  number,  you  should  manually  initialize  the  disk 
drive  with  the  following  command: 

OPEN   1,8, 15, "10 

Remember,  you  need  to  initialize  only  when  you  change  diskettes,  and  then 
only  if  the  ID  and  name  of  the  current  diskette  are  the  same  as  that  of  the  new 
diskette. 

Note  that  once  a  program  has  been  loaded  into  memory,  whether  from 
tape,  from  diskette,  or  by  hand,  the  computer  will  treat  it  in  the  same  manner; 
the  procedures  for  running,  listing,  and  making  changes  to  the  program 
remain  the  same. 

Formatting  a  Diskette 

The  computer  stores  and  retrieves  data  from  the  diskette  by  accessing  sectors 
on  the  diskette.  Each  sector  is  a  small  part  of  the  tracks  on  the  diskette.  Tracks 
are  similar  to  the  grooves  in  a  phonograph  record,  but  they  are  arranged  in 
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FIGURE  2-1.  A  diskette's  recorded  surface 


concentric  circles  rather  than  as  a  spiral.  Figure  2-1  shows  what  the  tracks 
and  sectors  on  a  diskette  might  look  like  if  you  could  see  them.  Each  sector 
may  contain  up  to  256  bytes  of  data  in  C-64  mode.  When  you  buy  a  new 
diskette,  it  is  not  divided  into  these  sectors  and  will  not  accept  anything  you 
try  to  record  on  it.  Therefore,  before  you  can  record  any  data  on  a  new 
diskette,  you  must  first  prepare  it  using  a  process  called  formatting.  The 
formatting  process  lays  out  sectors  on  the  diskette  so  that  data  can  be  stored 
on  it.  Diskettes  are  not  formatted  when  you  buy  them  because  each  disk  drive 
manufacturer  uses  a  slightly  different  format  on  its  diskettes.  The  C-128 
diskette  must  be  formatted  on  a  C-128  disk  drive. 
Here  are  two  methods  of  formatting  a  diskette. 
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Method  1: 

OPEN  1,8,15 

PRINT#l,"Ndnve  number.disk  name  J D  number" 

Example: 
OPEN  1,8,15 

PRINTttl ,  "N • NEW  DISK, 01" 

The  drive  number  may  be  omitted  when  there  is  only  one  disk  drive 
connected  to  the  C-128. 

Method  2: 

OPEN  l,8,15,"Nrfrive  number.disk  name  fir 
Example: 

OPEN  1,8, 15, "N: NEW  DISK, 01" 

Again,  the  drive  number  may  be  omitted  in  one-drive  systems. 

If  you  have  a  diskette  that  has  been  used  before  and  you  wish  to  erase  it 
completely  and  then  prepare  it  for  use  as  a  new  diskette,  you  may  simply  type 
a  command  of  the  format  OPENl,8,5,"Ndnve  number.disk  name". 

Example: 

OPEN  1,8, 15, "N" NEW  DISK" 

As  before,  the  drive  number  is  not  necessary  in  one-drive  systems,  and  in 
these  examples  the  ID  number  is  intentionally  left  out.  The  new  disk  name  is 
put  onto  the  diskette,  and  the  old  ID  number  is  used.  All  the  programs  and 
data  stored  on  the  diskette  will  be  erased.  Do  not  confuse  this  operation  with 
initialization,  which  sets  up  the  disk  and  drive  for  use  together.  Formatting 
will  erase  everything  from  your  diskette. 

Saving  a  Program 

Saving  a  program  onto  a  diskette  is  nearly  the  same  as  saving  a  program  onto 
tape  using  the  Datassette.  The  major  difference  is  in  the  wording  (syntax)  of 
the  command.  To  save  a  program  on  diskette,  type  a  command  of  the  format 
SAHE"program  name",8. 

If  you  only  have  one  disk  drive,  you  may  delete  the  drive  number.  For 
example,  to  save  the  "RALPH"  program  discussed  earlier  in  this  chapter, 
enter  it  and  type 
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SAVE  "RALPH", 8 

The  disk  drive  should  activate,  the  red  light  on  its  front  should  switch  on, 
the  video  screen  should  show 

SAVING  RALPH 

and  the  cursor  should  disappear.  When  the  program  has  been  saved,  the 
screen  will  show  the  READY  message  and  the  cursor  will  return. 

After  you  save  any  program,  it  is  a  good  idea  to  verify  it.  To  verify 
RALPH,  which  you  stored  on  diskette,  type 

VERIFV"RALPHM,8 

If  the  program  was  successfully  saved,  the  screen  will  display 

SEARCHING  FOR  RALPH 

VERIFYING 
OK 

READY. 

If  not,  you  will  get  the  7VERIFY  error  message.  If  this  occurs,  try  saving  and 
verifying  again. 

There  will  occasionally  be  flaws  on  a  diskette's  surface.  If  you  try  to  save 
a  program  and  cannot  get  it  to  save  properly,  there  may  be  a  slight  defect  in 
the  track  and  sector  being  accessed.  Try  another  diskette  in  this  case. 

OPERATING  THE  MPS  803 
GRAPHIC  PRINTER 

You  may  use  the  MPS  803  Graphic  Printer  to  print  the  data  from  your 
programs  and  to  list  the  programs  themselves.  The  printer  may  be  addressed 
in  either  immediate  or  program  mode. 

The  OPEN  Statement 

Before  you  can  send  data  to  the  printer,  you  must  open  a  channel  to  it.  This  is 
done  with  a  statement  of  the  format  OPEN  number  between  1  and  255,4. 

The  first  number  (between  1  and  255)  is  the  number  you  will  use  to 
address  the  printer.  The  second  number  is  the  printer's  device  number.  It  is 
usually  4. 

Here  is  an  example  of  a  printer  OPEN  statement. 
OPEN  1,4 
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You  would  now  send  all  the  data  to  be  printed  by  the  printer  to  channel  1 
by  typing 

PRINT#1 j   "HOW  NOW  BROWN  COWM 

The  printer  should  print  HOW  NOW  BROWN  COW  and  return,  advancing 
the  paper  one  row. 

In  a  program,  you  could  alternately  print  to  the  printer  and  the  video 
screen  by  simply  typing  PRINT  when  you  want  output  to  the  screen,  and 
PRINT#1  when  you  want  the  output  printed  on  the  printer.  PRINT  always 
outputs  to  the  primary  device  (the  screen,  for  example,  or  another  device 
selected  by  a  CMD  instruction).  PRINT#  outputs  to  a  file  specially  OPENed 
to  that  device  number. 

The  CMD  Statement 

If  you  had  a  program  that  displayed  all  its  data  on  the  screen  and  you  wanted 
it  to  print  everything  on  the  printer  instead,  you  could  accomplish  this  by 
adding  two  lines  to  the  beginning  of  the  program. 

OPEN  1,4 
CMD  1 

The  OPEN  statement  opens  a  channel  to  the  printer,  and  the  CMD  statement 
sends  all  output  to  the  printer.  By  doing  this,  every  PRINT  statement  is 
automatically  sent  to  the  printer. 

The  CMD  statement  also  allows  you  to  produce  a  printed  listing  of  a 
diskette's  directory.  To  do  this,  type 

LORD" $",8 

This  will  load  the  directory  into  memory.  Now  type 

OPEN  1,4 
CMD  1 
LIST 

This  will  generate  a  complete  directory  listing  on  the  printer.  This  will  also 
allow  you  to  produce  a  printed  copy  of  your  disk  directory,  should  you  want  to 
put  it  in  the  envelope  with  the  diskette. 

To  exit  from  the  CMD  mode,  enter  a  statement  of  the  format  PRINT# 
device  number. 
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The  CLOSE  Statement 

After  you  have  finished  using  the  printer,  you  must  close  the  channel  to  it.  To 
do  this,  type  a  statement  of  the  format  CLOSE  channel  number.  If  you 
OPENed  channel  1  (as  was  done  earlier),  type 

CLOSE  1 

After  using  a  CMD  statement,  you  will  need  to  precede  the  CLOSE 
statement  with  a  PRINTS  statement.  Here  is  an  example. 

OPEN  1,4 
CMD  1 


PRINT#1  :  CLOSE  1 

This  will  ensure  that  all  files  are  properly  closed.  Failing  to  do  this  may  cause 
file  errors. 


CHAPTER 


Programming 
The  C-128  Computer  ^} 


This  chapter  will  teach  you  how  to  program  your  C-128  using  BASIC,  its 
built-in  language.  If  you  are  already  familiar  with  BASIC,  Appendixes  E  and 
F  will  serve  as  a  comprehensive  reference  to  each  statement  in  the  language. 
If  you  are  a  beginner,  start  with  this  chapter.  It  will  give  you  the  background 
necessary  to  continue  through  the  rest  of  the  book. 

ELEMENTS  OF  A  PROGRAMMING 
LANGUAGE 

Program  statements  must  follow  a  well-defined  set  of  rules.  These  rules,  taken 
together,  are  referred  to  as  syntax.  There  are  many  different  sets  of  rules  that 
define  how  program  statements  are  written.  Each  set  of  rules  applies  to  a 
different  programming  language.  All  of  the  syntax  rules  described  in  this 
book  apply  only  to  C-128  BASIC. 

Programming  languages  are  as  varied  as  spoken  languages.  Common 


55 


56     C-1 28  USER  GUIDE 


programming  languages  include  BASIC,  Pascal,  FORTRAN,  COBOL,  APL, 
PL/  M,  PL-1,  and  FORTH.  Uncommon  programming  languages  number  in 
the  hundreds. 

The  variety  of  programming  languages  does  not  stop  here,  however, 
because  programming  languages,  like  spoken  languages,  have  dialects.  While 
a  BASIC  program  written  for  the  C-128  will  run  on  your  C-128,  it  may  not  run 
on  another  computer,  even  if  the  other  computer  is  also  programmable  in 
BASIC.  These  variations  in  language  syntax  are  due  to  the  computer's 
limitations  or  special  features.  However,  having  learned  how  to  program  your 
C-128  in  BASIC,  you  will  have  little  trouble  learning  the  BASIC  dialect  of  any 
other  computer. 

Some  syntax  rules  are  obvious.  The  addition  and  subtraction  examples 
in  Chapter  2  use  obvious  syntax;  so  you  do  not  have  to  be  a  programmer  to 
understand  these  simple  calculation  statements.  However,  most  syntax  rules 
seem  arbitrary,  and  sometimes  they  are.  For  example,  why  use  *  to  represent 
multiplication?  You  would  normally  use  X  for  multiplication;  but  the  com- 
puter would  have  no  way  of  differentiating  between  the  use  of  the  X  sign  to 
represent  multiplication  and  the  letter  x.  Therefore,  nearly  all  computer 
languages  use  the  asterisk  (*)  to  represent  multiplication.  Division  is 
universally  represented  by  a  slash  (/).  Since  the  standard  division  sign  (-r)  is 
not  present  on  computer  or  typewriter  keyboards,  some  other  character  had 
to  be  selected.  The  slash  was  probably  chosen  because  it  made  the  program 
expression  look  like  a  fraction. 

BASIC  statement  syntax  handles  line  numbers,  data,  and  instructions  to 
the  computer  in  different  ways.  Each  will  be  described  in  turn. 

Line  Numbers 

In  program  mode  every  line  of  a  BASIC  program  must  have  a  unique  line 
number.  The  first  line  of  the  program  must  have  the  smallest  line  number, 
while  the  last  line  must  have  the  largest.  The  line  numbers  in  between  must  be 
in  ascending  order.  The  C-128  computer  forces  this  upon  you:  no  matter 
where  you  enter  a  line  on  the  display,  the  C-128  will  move  it  to  its  proper 
sequential  position.  Consider  an  existing  program  with  the  following  line 
numbers: 

120 
130 
140 
150 
160 
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170 
180 
190 

If  you  enter  a  new  statement  with  line  number  165,  the  new  statement  will 
initially  appear  below  the  existing  line  190,  but  the  computer  will  automati- 
cally insert  this  statement  between  lines  160  and  170.  This  may  be  illustrated 
as  follows: 

Line  numbers  displayed  Lines  stored  and 

when  you  entered  line  165  redisplayed  thus 


120 

120 

130 

130 

140 

140 

150 

150 

160 

160 

170 

165 

180 

170 

190 

180 

190 

165 

If  the  line  number  of  a  new  statement  duplicates  an  existing  line  number, 
the  old  statement  will  be  replaced. 

C-128  BASIC  allows  line  numbers  to  range  between  1  and  63999.  The 
C-128  computer  interprets  digits  appearing  at  the  beginning  of  any  line  as  the 
line  number.  If  the  line  number  is  larger  than  63999,  a  syntax  error  message 
appears,  since  you  have  violated  one  of  the  syntax  rules  for  C-128  BASIC. 

As  noted  earlier,  all  BASIC  dialects  require  line  numbers  to  be  assigned 
in  ascending  order;  however,  the  largest  line  number  allowed  varies  from  one 
dialect  of  BASIC  to  the  next. 

You  use  line  numbers  as  addresses  that  identify  locations  within  a 
program.  This  is  an  important  concept,  since  every  program  will  contain  the 
following  two  types  of  statements: 

1.  Statements  that  create  or  modify  data. 

2.  Statements  that  control  the  sequence  in  which  operations  are 
performed. 

The  idea  that  operations  specified  by  a  program  must  be  performed  in 
some  well-defined  sequence  is  a  simple  enough  concept.  Program  execution 
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normally  begins  with  the  first  statement  in  the  program  and  continues 
sequentially.  This  may  be  illustrated  as  follows: 

Start  -10^ 

^etc. 


Most  programs,  however,  contain  some  nonsequential  execution  sequences. 
Line  numbers  then  become  important  because  they  are  used  to  identify  a 
change  in  execution  sequence.  This  may  be  illustrated  as  follows: 


Data 

The  statement  or  statements  following  a  line  number  specify  operations  the 
computer  is  to  perform,  as  well  as  data  that  must  be  used  while  performing 
these  operations.  The  next  few  pages  describe  the  types  of  data  you  may 
encounter  in  a  C-128  BASIC  program. 

There  are  two  kinds  of  numbers  that  can  be  stored  in  C-128  computers: 
floating  point  numbers  (also  called  real  numbers)  and  integers. 


FLOATING  POINT  NUMBERS 

Floating  point  is  the  standard  number  representation  used  by  C-128 
computers.  All  arithmetic  is  performed  with  floating  point  numbers.  The 
name  refers  to  the  decimal  point's  ability  to  float,  allowing  the  use  of  fractions 
with  different  numbers  of  digits.  A  floating  point  number  can  be  a  whole 
number  or  a  fractional  number  preceded  by  a  decimal  point.  The  number  can 
be  negative  (— )  or  positive  (+).  If  the  number  has  no  sign,  it  is  assumed  to  be 
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positive.  Here  are  some  examples  of  floating  point  numbers  that  are  equiv- 
alent to  integers. 

5 

-15 
65000 
161 
0 

Here  are  examples  of  floating  point  numbers  that  include  a  decimal 
point. 

0.5 

0.0165432 
-0.0000009 

1.6 
24.0055 
-64.2 
3.1416 

Note  that  if  you  put  commas  in  a  number,  you  will  get  a  syntax  error  message. 
For  example,  use  65000,  not  65,000. 

ROUNDOFF 

Numbers  always  have  at  least  eight  digits  of  precision;  they  can  have  up 
to  nine  depending  on  the  number.  C-128  BASIC  rounds  off  additional 
significant  digits.  Usually  it  rounds  up  when  the  next  digit  is  more  than  5  and 
rounds  down  when  the  next  digit  is  4  or  less,  but  there  are  some  roundoff 
quirks.  Here  are  some  examples. 


7.5555555556 
. 555555555 

4  

7.5555555557 
. 555555556 


,1111111115 
,111111111 

4_ 


1111111116 

,111111112 


Rounds  down  on  6 

or  less,  up  on  7  or  more 


Rounds  down  on  5  or 
less,  up  on  6  or  more 
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SCIENTIFIC  NOTATION 

Large  floating  point  numbers  are  shown  in  scientific  notation.  When 
numbers  with  ten  or  more  digits  are  entered,  C-128  BASIC  automatically 
converts  these  numbers  to  scientific  notation. 

REflDV. 
71111  111  114 
1. 11111111E+09 

REfiDV. 

71111111115 
1.  111111 12E+09 

A  number  in  scientific  notation  has  the  following  form: 

number  E  +  ee 

where 

number  is  an  integer,  fraction,  or  combination.  The  "number"  por- 
tion contains  the  number's  significant  digits;  it  is  called 
the  coefficient.  If  no  decimal  point  appears,  it  is  assumed 
to  be  to  the  right  of  the  coefficient. 

E  is  always  the  letter  E.  It  substitutes  for  the  word 

"exponent." 

+  is  an  optional  plus  sign  or  minus  sign. 

ee  is  a  one-digit  or  two-digit  exponent.  The  exponent  specifies 

the  magnitude  of  the  number:  the  number  of  places  to 
the  right  (positive  exponent)  or  to  the  left  (negative 
exponent)  that  the  decimal  point  must  be  moved  to  give 
the  true  decimal  point  location. 

Here  are  some  examples. 


Scientific  Notation 

2E1 
10.5E+4 

66E+2 

66E-2 
-66E-2 

IE- 10 

94E20 


Standard  Notation 

20 

105000 
6600 
0.66 
-0.66 

0.0000000001 
9400000000000000000000 


Scientific  notation  is  a  convenient  way  of  expressing  very  large  or  very 
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small  numbers.  C-128  BASIC  prints  numbers  ranging  between  0.01  and 
999,999,999  in  standard  notation,  but  numbers  outside  of  this  range  are 
printed  in  scientific  notation.  Here  are  some  examples. 

7.009 
9E-83 

REflDV. 
7.01 
.01 

RE ADV. 

?999999998 .9 

9999999999 

RERDV. 

7999999999.6 
1E+09 


Even  when  you  use  scientific  notation,  there  is  a  limit  to  the  size  of  a 
number  that  C-128  BASIC  can  handle.  The  limits  are 

Largest  floating  point  number:  +1.70141183+38 
Smallest  floating  point  number:  +2.93873588E-39 

Any  number  of  a  larger  magnitude  will  give  an  overflow  error.  The  following 
are  examples  of  overflow  errors: 

71. 70141 183E+38  \ 
1. 78141 183E+38  I 

RERDV.  /  No  Overflow  error 

7-1. 70141 183E+38  I 
-1. 78141 183E+38 

RERDV. 

71.78141184E+38 

70VERFL0W  ERROR 
RERDV. 

7-1. 70141 184E+38 
70VERFL0W  ERROR 


A  number  that  is  smaller  than  the  smallest  magnitude  will  yield  a  zero  result. 
This  may  be  illustrated  as  follows: 

72.93873588E-39 
2.93873588E-39 

RERDV. 

7-2.93873588E-39 
-2.93873588E-39 


Overflow  error 
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REflDV. 

?2-93873587E~39 
0 

REflDV. 

7-2.93873587E-39 
0 


INTEGERS 

An  integer  is  a  number  that  has  no  fraction  or  decimal  point.  The 
number  can  be  negative  (— )  or  positive  (+).  An  unsigned  number  is  assumed 
to  be  positive.  Because  of  the  way  in  which  they  are  stored  in  the  computer, 
integers  must  have  values  in  the  range  —32768  to  +32767.  Here  are  some 
examples  of  integers. 

0 
1 

44 
32699 
-15 

Any  integer  can  also  be  represented  as  a  floating  point  number,  since 
integers  are  a  subset  of  floating  point  numbers.  C-128  BASIC  automatically 
converts  integers  to  floating  point  numbers  before  using  them  in  arithmetic. 

STRINGS 

The  word  string  is  used  to  describe  data  that  consists  of  characters.  This 
can  be  anything  that  is  not  interpreted  as  a  number. 

You  have  already  used  strings  as  messages  to  be  displayed  on  the  C-128's 
screen.  A  string  consists  of  one  or  more  characters  enclosed  in  double 
quotation  marks,  as  shown  here: 

"HI!" 

"SYNERGY" 
"12345" 

"$10.44  IS  THE  AMOUNT" 

"22  UNION  SQUARE,  SAN  FRANCISCO,  CA" 

Within  a  string  you  can  include  any  alphabetic  or  numeric  characters, 
special  symbols  or  graphic  characters,  cursor  control  characters  (CLR /  HOME, 
CRSR  UP/  DOWN,  CRSR  LEFT/  RIGHT),  and  the  RVS  ON/  OFF  keys.  The  only  keys 
that  cannot  be  used  within  a  string  are  RUN/ STOP,  RETURN,  and  INS/ DEL. 

All  characters  within  the  string  are  displayed  as  they  appear.  The  cursor 
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control,  color  control,  and  RVS  ON/  OFF  keys,  however,  normally  do  not  print 
anything  themselves.  To  show  that  these  keys  are  present  in  a  string,  certain 
reverse  field  symbols  are  used,  as  shown  in  Table  3-1. 

Strings  are  entered  as  part  of  a  statement.  A  statement  must  fit  within  an 
80-character  line,  so  the  longest  string  you  can  enter  at  the  keyboard  will  have 
less  than  80  characters,  since  there  must  be  room  for  the  line  number. 

Strings  of  up  to  255  characters  can  be  stored  in  memory.  Long  strings  are 
generated  by  concatenation  (the  joining  together  of  shorter  strings).  This  will 
be  explained  later  in  this  chapter. 

VARIABLES 

The  concept  of  a  variable  is  easy  to  understand.  Consider  the  following 
statements: 

100  fl*B+C 
200  ?R 


TAB1E3-1.  Special  String  Symbols 


Function 

Key 

String  Symbol 

Reverse  On 

CTRL 

RVS 
ON 

Q 

(Reverse  R) 

Reverse  Off 

CTRL 

r  > 

RVS 

OFF 

B 

(Reverse  Shifted 

R) 

Home  Cursor 

f 

CLR 
HOME 

m 

(Reverse  S) 

Clear  Screen 

Shifted 

CLR 
HOME 

Li 

(Reverse  Shifted 

S) 

Cursor  Down 

f  s 

A 

CRSR 

,  v  J 

or 

CRSR 

V 

(Reverse  Q) 

Cursor  Up 

Shifted 

CRSR 

- 

CRSR 

(Reverse  Shifted 

Q) 

Cursor  Right 

f  <=  I 

CRSR 

l=>  J 

or 

f 

CRSR 

^  J 

u 

(Reverse  ]) 

Cursor  Left 

Shifted 

'<=  I 
CRSR 

or 

CRSR 

n 

(Reverse  Shifted 

]) 

i=>  J 
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These  two  statements  cause  the  sum  of  two  numbers  to  be  displayed.  The  two 
numbers  are  whatever  B  and  C  represent  at  the  time  that  the  statements  are 
executed.  In  the  following  example, 

90  B»4.65 
95  03.72 
100  fl*B+C 
200  ?fi 

B  is  assigned  the  value  4.65,  while  C  is  assigned  the  value  3.72.  Therefore,  A 
equals  8.37. 

VARIABLE  NAMES 

Variable  names  can  be  used  to  represent  string  data  or  numeric  data.  If 
you  have  studied  elementary  algebra,  you  will  have  no  trouble  understanding 
the  concept  of  variables  and  variable  names.  If  you  have  never  studied 
algebra,  then  think  of  a  variable  name  as  a  name  assigned  to  a  mailbox. 
Anything  that  is  placed  in  the  mailbox  becomes  the  value  associated  with  the 
mailbox  name. 

A  variable  name  can  have  one,  two,  or  three  characters.  The  following 
character  options  are  allowed. 


Third  character  must  be  $  for  a  string  variable  or 
%  for  an  integer  variable.  A  floating  point 
variable  name  can  only  have  two  characters. 

Second  character  can  be  any  unshifted  letter 
(A  to  Z)  or  any  numeric  digit  (1,  2,  3,  4,  5,  6,  7,  8,  9,  0) 
for  any  type  of  variable. 

First  character  must  be  an  unshifted  letter 
(A  to  Z)  for  any  type  of  variable. 


Thus,  the  last  character  of  the  variable  name  tells  C-128  BASIC  which  type  of 
data  the  variable  represents. 

Note  that  unshifted  letters  are  used  for  the  first  and  second  label  charac- 
ters. Depending  on  the  mode  of  the  computer,  unshifted  letters  may  be 
uppercase  or  lowercase.  Either  way,  they  are  the  letters  displayed  when  the 
SHIFT  key  is  not  being  depressed. 

Floating  point  variables  are  the  ones  most  frequently  used  in  C-128 
BASIC.  Here  are  some  examples  of  floating  point  variable  names, 


A 
B 

C 
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Al 

AA 

Z5 


A% 

B% 

C% 

Al% 

MN% 

X4% 


A$ 
M$ 
MN$ 
MIS 

zx$ 

F6$ 

Variable  names  can  have  more  than  two  alphanumeric  characters,  but 
only  the  first  two  characters  count.  Therefore,  BANANA  and  BANDAGE  are 
interpreted  as  the  same  name,  since  both  begin  with  BA.  C-128  BASIC  allows 
variable  names  to  have  up  to  86  characters,  but  such  large  names  are  imprac- 
tical. Four  to  eight  characters  is  a  more  realistic  limit;  long  names  may 
actually  make  it  harder  to  read  your  program.  The  following  names  illustrate 
the  way  C-128  BASIC  "sees"  long  variable  names: 


MAGICS 

interpreted  as 

MAS 

N 123456789 

interpreted  as 

Nl 

MMMS 

interpreted  as 

MMS 

ABCDEF% 

interpreted  as 

AB% 

CALENDAR 

interpreted  as 

CA 

If  you  use  variable  names  with  more  than  two  characters,  keep  the 
following  points  in  mind: 

1.  Only  the  first  two  characters  plus  the  identifier  symbol  ($  or  %)  are 
significant.  Do  not  use  extended  names  like  LOOP1  and  LOOP2; 
these  are  interpreted  as  the  same  variable:  LO. 

2.  C-128  BASIC  has  a  number  of  reserved  words  that  have  special 
meaning  within  a  BASIC  statement.  Reserved  words  include  BASIC 


integer  variable  names, 


and  string  variable  names. 
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statements,  such  as  PRINT,  and  others  that  will  be  discussed  later  in 
the  chapter.  A  reserved  word  cannot  be  embedded  anywhere  in  a 
name.  For  example,  you  cannot  use  PRINTER  as  a  variable  name, 
because  BASIC  would  see  it  as  "PRINT  ER."  This  problem  usually 
shows  up  as  a  syntax  error  in  a  line  that  looks  correct. 

3.  Additional  characters  use  up  memory  space  that  you  might  need  in 
longer  programs.  On  the  other  hand,  longer  variable  names  make 
programs  easier  to  understand.  PARTNO,  for  example,  is  more 
meaningful  than  PA  as  a  variable  name  describing  part  numbers  in  an 
inventory  program. 

Operators 

The  BASIC  statement 
100  710.2+4.7 

tells  the  C-128  to  add  10.2  and  4.7,  and  then  display  the  sum.  The  statement 
250  Ofi+B 

tells  the  C-128  to  add  the  two  floating  point  numbers  represented  by  the 
variable  names  A  and  B,  and  to  assign  the  sum  to  the  floating  point  number 
represented  by  the  variable  name  C. 

The  plus  sign  is  referred  to  as  an  operator.  It  is  an  arithmetic  operator, 
since  addition  is  an  arithmetic  operation.  There  are  two  other  types  of 
operators:  relational  operators  and  Boolean  operators.  These  require  a  little 
more  explanation,  since  they  reflect  conditions  and  decisions  rather  than 
arithmetic. 

Table  3-2  summarizes  the  BASIC  operators.  You  will  examine  each 
group  of  operators  in  turn,  beginning  with  arithmetic  operators. 

ARITHMETIC  OPERATORS 

An  arithmetic  operator  specifies  addition,  subtraction,  multiplication, 
division,  or  exponentiation.  Arithmetic  operations  are  performed  with  float- 
ing point  numbers.  Integers  are  automatically  converted  to  floating  point 
numbers  before  an  arithmetic  operation  is  performed,  and  the  result  is 
automatically  converted  back  to  an  integer  if  an  integer  variable  represents 
the  result. 

The  data  operated  on  by  any  operator  is  referred  to  as  an  operand.  Each 
arithmetic  operator  requires  two  operands,  which  may  be  numbers,  numeric 
variables,  or  a  combination  of  both. 
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TABLE  3-2.  Operators 


Precedence 

Operator 

Meaning 

High 

9 

() 

Parentheses  denote  order  of  evaluation 

8 

t 

Exponentiation 

0>  O 

7 

— 

Unary  minus 

s  3 

6 

Multiplication 

0 

/ 

Division 

5 

+ 

Addition 

5 

Subtraction 

4 

Equal 

Not  equal 

II 

4 

< 

Less  than 

4 

> 

Greater  than 

«  o 

4 

<  =  or  =  < 

Less  than  or  equal 

4 

>=  or=> 

Greater  than  or  equal 

So 

3 

NOT 

Logical  complement 

2 

AND 

Logical  AND 

o  »- 

1 

OR 

Logical  OR 

** 

Low 

Addition  (+).  The  plus  sign  specifies  that  the  data  (or  operand)  on  the 
left  of  the  plus  sign  is  to  be  added  to  the  data  (or  operand)  on  the  right.  For 
numeric  quantities,  this  is  straightforward  addition. 

The  plus  sign  is  also  used  to  "add"  strings.  In  this  case,  however,  the  plus 
sign  does  not  add  the  values  of  the  strings.  Instead,  the  strings  are  joined 
together,  or  concatenated,  to  form  one  longer  string.  The  difference  between 
numeric  addition  and  string  concatenation  can  be  visualized  as  follows: 

Addition  of  numbers:  numl+num2=  num3 
Addition  of  strings:  string  1 + string2  =  string lstring2 

Using  concatenation,  you  can  develop  strings  containing  up  to  255 
characters. 

"FOR"+"WARD"  results  in  "FORWARD" 

"HI"+  "  "  +"THERE"       results  in  "HI  THERE" 

A$+  B$  results  in  concatenation  of  the  two  strings 

represented  by  string  variable  labels  A$ 
and  B$ 
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"  1 "+  CH$+  E$  results  in  the  character  "  1 followed  by 

concatenation  of  the  two  strings 
represented  by  string  variable  labels 
CHS  and  E$ 

If  A$  is  set  equal  to  "FOR"  and  B$  is  set  equal  to  "WARD,"  then  A$+B$ 
would  generate  the  same  result  as  "FOR"+"WARD." 

Should  you  try  to  build  a  string  longer  than  255  characters,  a  STRING 
TOO  LONG  error  is  displayed. 

Subtraction  (— ).  The  minus  sign  specifies  that  the  operand  on  the  right 
of  the  minus  sign  is  to  be  subtracted  from  the  operand  on  the  left  of  the  minus 
sign.  For  example: 

4—  1  results  in  3 

100-64      results  in  36 

A— B         results  in  the  variable  represented  by  label  B  being  sub- 
tracted from  the  variable  represented  by  label  A 

55-142      results  in -87 

The  unary  minus  operator  identifies  a  negative  number.  For  example: 

-5 
-9E4 
-B 
4  2 

Note  that  4  2  is  the  same  as  4+2. 

Multiplication  (*).  An  asterisk  specifies  that  the  operand  on  the  right  of 
the  asterisk  is  to  be  multiplied  by  the  operand  on  the  left  of  the  asterisk.  Here 
are  some  examples. 

100  *  2     results  in  200 
50  *  0       results  in  0 

A  *  XI     results  in  multiplication  of  two  floating  point  numbers 

represented  by  floating  point  variables  labeled  A  and  XI 

R%  *  14   results  in  an  integer  represented  by  integer  variable  label 
R%  being  multiplied  by  14 

In  these  examples,  if  variable  A  is  assigned  the  value  4.2  and  variable  X 1 
is  assigned  the  value  9.63,  the  answer  would  be  40.446.  A  and  XI  could  hold 
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integer  values  100  and  2  to  duplicate  the  first  example;  however,  the  two 
numbers  would  be  held  in  the  floating  point  format  as  100.0  and  2.0,  since  A 
and  XI  are  floating  point  variables.  In  order  to  multiply  100  by  2,  represent- 
ing these  numbers  as  integers,  you  would  have  to  write  the  example  as  A%  * 


Division  (/).  The  slash  specifies  that  the  operand  on  the  left  of  the  slash  is 
to  be  divided  by  the  data  (or  operand)  on  the  right  of  the  slash.  For  example: 


4E2/XR     results  in  400  being  divided  by  the  floating  point  number 
represented  by  label  XR 

The  third  example,  A /  B,  can  duplicate  the  first  or  second  examples,  even 
though  A  and  B  represent  floating  point  numbers.  The  integer  numbers 
would  be  held  in  floating  point  form,  however,  A%/  B%  could  exactly  dupli- 
cate either  of  the  first  two  examples. 

Exponentiation  (t ).  The  up  arrow  specifies  that  the  operand  on  the  left  of 
the  arrow  is  raised  to  the  power  specified  by  the  operand  on  the  right  of  the 
arrow.  If  the  data  (or  operand)  on  the  right  is  2,  the  number  on  the  left  is 
squared;  if  the  data  (or  operand)  on  the  right  is  3,  the  number  on  the  left  is 
cubed;  and  so  on.  The  exponent  can  be  any  number,  variable,  or  expression, 
as  long  as  the  exponentiation  yields  a  number  in  the  allowed  floating  point 
range.  For  example: 

2 1  2  results  in  4 

12 1  2  results  in  144 

1 1  3  results  in  1 

A  f  5  results  in  the  floating  point  number  assigned  to  variable  A 

being  raised  to  the  fifth  power 

2 1  6.4         results  in  84.4485064 

NM  t  —  10  results  in  the  floating  point  number  assigned  to  variable 
NM  being  raised  to  the  negative  tenth  power 

14 1  F         results  in  14  being  raised  to  the  power  specified  by  floating 


Xl%. 


10/2 

6400/4 

A/B 


results  in  5 


results  in  the  floating  point  number  assigned  to  variable  A 
being  divided  by  the  floating  point  number  assigned  to 
variable  B 


results  in  1600 


point  variable  F 
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ORDER  OF  EVALUATION 

An  expression  may  have  multiple  arithmetic  operations,  as  in  the  follow- 
ing statement: 

A+C*  10/2t  2 

When  this  occurs,  there  is  a  fixed  sequence  in  which  operations  are  processed. 
First  comes  exponentiation  (t),  followed  by  sign  evaluation,  followed  by 
multiplication  and  division  (*  / ),  and  then  by  addition  and  subtraction  (H — ). 
Operations  of  equal  precedence  are  evaluated  from  left  to  right.  This  order  of 
operations  can  be  overridden  by  the  use  of  parentheses.  Any  operation  within 
parentheses  is  performed  first.  For  example: 

4+ 1  *  2  results  in  6 

(4+1)  *  2  results  in  10 

100  *  4/2-1  results  in  199 

100  *  (4/2-1)  results  in  100 

100  *  (4/(2-1))       results  in  400 

When  parentheses  are  present,  C-128  BASIC  evaluates  the  innermost  set 
first,  then  the  next  innermost,  and  so  on.  Parentheses  can  be  nested  to  any 
level  and  may  be  used  freely  to  clarify  the  order  of  operations  being  per- 
formed in  an  expression. 

RELATIONAL  OPERATORS 

Relational  operators  represent  the  following  conditions:  greater  than 
(>),  less  than  (<),  equal  to  (=),  not  equal  to  (<  >),  greater  than  or  equal  to 
(>=),  and  less  than  or  equal  to  (<=).  Here  are  some  examples. 

1=5—4        results  in  true(— 1) 
14>66         results  in  false  (0) 
15  >=  15       results  in  true(—  1) 

AOB       the  result  will  depend  on  the  values  assigned  to  floating 
point  variables  A  and  B 

C-128  BASIC  arbitrarily  assigns  a  value  of  0  to  a  "false"  condition  and  a 
value  of  —  1  to  a  "true"  condition.  These  0  and  —1  values  can  be  used  in 
equations.  For  example,  in  the  expression  (1  =  1)  *  4,  the  equation  (1  =  1)  is 
true.  True  equates  to  —1;  therefore,  the  expression  is  the  same  as  (—1)  *  4, 
which  results  in  —4.  You  can  include  any  relational  operators  within  a  C-128 
BASIC  expression.  Here  are  some  examples. 
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25+(l4>66)  is  the  same  as  25+0 

(A+(l=5-4)  *  (I5>=l5)     is  the  same  as  (A-l)*(-l) 

Relational  operators  can  be  used  to  compare  strings.  For  comparison 
purposes,  the  letters  of  the  alphabet  have  the  order  A<  B,  B<  C,  C<  D,  and 
so  on.  Strings  are  compared  one  character  at  a  time,  starting  with  the  leftmost 
character. 

"A"<"B"  results  in  true  (-1) 

"X"=  "XX"       results  in  false  (0) 

C$=  A$+  B$      result  will  depend  on  the  string  values  assigned  to 
the  three  string  variables  C$,  B$,  and  A$ 

When  operating  on  strings,  C-128  BASIC  generates  a  value  of  —  l  for  a 
"true"  result,  and  a  value  of  0  for  a  "false"  result. 

("JONES">"DOE")+37  is  the  same  as  - 1+37 

("AAA"<"AA")*(Z9-("OTTER">"AB"))     is  the  same  as  0*(Z9- 

(-0) 

BOOLEAN  OPERATORS 

Boolean  operators  give  programs  the  ability  to  make  logical  decisions. 
There  are  three  Boolean  operators  in  C-128  BASIC:  AND,  OR,  and  NOT. 

A  simple  shopping  analogy  can  serve  to  illustrate  Boolean  logic.  Sup- 
pose you  are  shopping  for  breakfast  cereals  with  two  children. 

The  AND  Boolean  operator  says  that  a  cereal  is  selected  only  if  child  A 
and  child  B  select  the  cereal. 

The  OR  Boolean  operator  says  that  a  cereal  will  be  selected  if  either  child 
A  or  child  B  selects  the  cereal. 

The  NOT  operator  generates  a  logical  opposite:  if  child  B  insists  on 
disagreeing  with  child  A,  then  child  B's  decision  is  always  not  child  A's 
decision. 

Table  3-3  summarizes  the  way  in  which  Boolean  operators  handle 
numbers.  This  table  is  referred  to  as  a  truth  table. 

Boolean  operators  primarily  control  program  logic.  Here  are  some 
examples. 

IF  A=l00  AND  B=l00  GOTO  10 

If  both  A  and  B  are  equal  to  100,  branch  to  line  10 
IF  X<  Y  AND  B>  =  44  THEN  F=0 

If  X  is  less  than  Y  and  B  is  greater  than  or  equal  to  44,  then  set 

F  equal  to  0 
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IF  A=100ORB=100GOTO20 

If  either  A  or  B  has  a  value  of  100,  branch  to  line  20 
IF  X<YORB>=44THENF=0 

F  is  set  to  0  if  X  is  less  than  Y  or  B  is  greater  than  43 
IF  A=l  AND  B=2  OR  C=3  GOTO  30 

Take  the  branch  if  both  A=l  and  B=2;  also  take  the  branch 

if  C=3 

A  single  operand  can  be  tested  for  true  or  false.  An  operand  appearing 
alone  has  an  implied  "<>0"  following  it.  Any  nonzero  value  is  considered 
true;  a  zero  value  is  considered  false. 

IF  A  THEN  B=  2 

IF  AO0  THEN  B=2 

These  two  statements  are  equivalent 
IF  NOT  B  GOTO  100 

Branch  if  B  is  false  (equal  to  zero).  This  is  probably  better 

written  as 
IF  B=0  GOTO  100 

All  Boolean  operations  use  integer  operands.  If  you  perform  Boolean 
operations  using  floating  point  numbers,  the  numbers  are  automatically 
converted  to  integers.  Therefore,  the  floating  point  numbers  must  fall  within 
the  allowed  range  of  integer  numbers. 

If  you  are  a  novice  programmer,  you  are  unlikely  to  use  Boolean 


TABIE  3-3.  Boolean  Truth  Table 


The  AND  operation  results  in  a  1  only  if  both  numbers  are  1 
1  AND  1 =  1 

0  AND  1  =  0 

1  AND  0=0 

0  AND  0=0 

The  OR  operation  results  in  a  1  if  either  number  is  1 

1  OR  1 =  1 
0  OR  1 =  1 
1 OR0  =  1 
0  OR 0=0 

The  NOT  operation  logically  complements  each  number 
NOT  1  =  0 
NOT  0  =  1 


PROGRAMMING  THE  C-1 28  COMPUTER  73 


operators  in  the  manner  that  is  about  to  be  described.  If  you  do  not  under- 
stand the  discussion,  skip  to  the  next  section. 

Boolean  operators  operate  on  integer  operands  one  binary  digit  at  a 
time.  C-128  BASIC  stores  all  numbers  in  binary  format,  using  two's  comple- 
ment notation  to  represent  negative  numbers.  Therefore,  an  AND  operation 
can  be  illustrated  as  follows: 

43  AND  137  =  9-  ■ 

I  ^89,6-  10001001 

1  »2B16 -00101011 

09,6-  00001001   

Here  is  an  OR  operation. 

43  OR  137  =  171   1 

I  -89,6-  10001001 

1  -2B16-  00101011 

AB16  —10101011  

Here  are  two  NOT  operations. 

NOT  43  =  212  1 

I  -2B,6-  00101011 

I  i 
D416-  11010100  1 

NOT  137=  118  1 

I  -8916-  10001001 

i  I 
7616-01110110  1 

If  operands  are  not  integers,  they  are  converted  to  integer  form;  the 
Boolean  operation  is  performed,  and  the  result  is  returned  as  a  0  or  1. 

If  a  Boolean  operator  has  relational  operands,  then  the  relational  oper- 
and is  evaluated  to  —  1  or  0  before  the  Boolean  operation  is  performed.  Thus, 
the  operation 

A=l  or  C<2 


is  equivalent  to 
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Consider  this  more  complex  operation. 

IF  A=B  AND  C<D  GOTO  40 

First,  the  relational  expressions  are  evaluated.  Assume  that  the  first  expres- 
sion is  true  and  the  second  one  is  false.  The  statement  becomes 

IF  — 1  AND  0  GOTO  40 

Performing  the  AND  yields  a  0  result. 

IF  0  GOTO  40 

Recall  that  a  single  term  has  an  implied  "<>0"  following  it.  The  expression 
therefore  becomes 

IF0O0  GOTO  40 

Thus,  the  branch  is  not  taken. 

In  contrast,  a  Boolean  operation  performed  on  two  variables  may  yield 
any  integer  number. 

IF  A%  AND  B%  GOTO  40 

Assume  that  A%=255  and  B%=240.  The  Boolean  operation  255  AND  240 
yields  240.  The  statement,  therefore,  becomes 

IF  240  GOTO  40 

or,  with  the  "<>0", 

IF  240O0  GOTO  40 

Therefore,  the  branch  will  be  taken. 

Now  compare  the  following  assignment  statements: 

A=  A  AND  10 
A=A<10 

In  the  first  example,  the  current  value  of  A  is  logically  ANDed  with  10,  and 
the  result  becomes  the  new  value  of  A.  Variable  A  must  be  in  the  integer  range 
—  32768  to  +  32767.  In  the  second  example,  the  relational  expression  A<10  is 
evaluated  to  —  1  or  0,  so  A  must  end  up  with  a  value  of  —  1  or  0. 

Arrays 

Arrays  are  used  in  many  types  of  computer  programs.  If  you  are  not  already 
familiar  with  arrays,  you  will  need  to  learn  about  them.  The  information  that 
follows  will  be  very  important  to  your  programming  efforts. 
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Conceptually,  arrays  are  very  simple.  When  you  have  two  or  more 
related  data  items,  instead  of  giving  each  data  item  a  separate  variable  name, 
you  give  the  collection  of  related  data  items  a  single  variable  name.  Then  you 
select  individual  items  with  a  position  number,  which  is  referred  to  as  a 
subscript,  or  index. 

A  grocery  list,  for  example,  may  have  six  items  from  the  meat  and 
poultry  department,  four  fruit  and  vegetable  items,  and  three  dairy  products. 
Each  of  these  three  groups  of  items  could  be  represented  by  a  single  variable 
name  as  follows: 


MP$(0)=  "CHOPPED  SIRLOIN" 
MP$(1)=  "CHUCK  STEAK" 
MP$(2)="NEW  YORK  STEAK" 
MP$(3)=  "CHICKEN" 
MP$(4)=  "SALAMI" 
MP$(5)="SAUSAGES" 


FV$(0)=  "ORANGES" 
FV$(1)="APPLES" 
FV$(2)=  "BEANS" 
FV$(3)="CARROTS" 

DP$(0)="MILK" 

DP$(1)="CREAM" 

DP$(2)=  "COTTAGE  CHEESE' 


MPS  is  a  single  variable  name  that  identifies  all  meat  and  poultry  products; 
FV$  identifies  fruits  and  vegetables;  and  DP$  identifies  dairy  products. 

A  subscript  follows  each  variable  name.  Thus,  a  specific  data  item  is 
identified  by  a  variable  name  and  an  index. 

Notice  that  the  first  index  value  in  the  examples  is  0,  not  1 .  Subscripts  in 
BASIC  start  from  0  because  this  simplifies  the  programming  of  many  scien- 
tific and  mathematical  problems.  Many  people  are  uncomfortable  with  this 
practice,  however.  If  you  don't  feel  at  home  with  using  element  0  of  an  array, 
simply  ignore  it  and  start  with  a  subscript  of  1 .  You  will  waste  a  little  memory 
space,  but  you  are  less  likely  to  make  programming  mistakes  if  you  are  not 
trying  to  "adapt"  yourself  to  the  machine. 

You  could  take  the  array  concept  one  step  further,  specifying  a  single 
variable  name  for  the  entire  grocery  list  by  using  two  indexes.  The  first  index 
(or  subscript)  specifies  the  product  type,  and  the  second  index  specifies  the 
item  within  the  product  type.  This  is  one  way  in  which  a  single  grocery-list 
variable  array  with  two  subscripts  could  replace  the  three  arrays  with  single 
subscripts  illustrated  earlier.  Here  are  some  examples. 


GL$(0,0)= 
GL$(0,1)= 
GL$(0,2)= 
GL$(0,3)= 
GL$(0,4)= 
GL$(0,5)= 


MP$(0) 
MP$(1) 
MP$(2) 
MP$(3) 
MP$(4) 
MP$(5) 


GL$(1,0)=FV$(0) 
GL$(1,1)=FV$(1) 
GL$(1,2)=FV$(2) 
GL$(1,3)=FV$(3) 


GL$(2,0)=DP$(0) 
GL$(2,1)=  DP$(1) 
GL$(2,2)=  DP$(2) 
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Arrays  can  represent  integer  variables,  floating  point  variables,  or  string 
variables.  However,  a  single  array  variable  can  only  represent  one  data  type. 
In  other  words,  a  single  variable  cannot  mix  integer  and  floating  point 
numbers.  One  or  the  other  can  be  present,  but  not  both. 

Arrays  are  a  useful  shorthand  means  of  describing  a  large  number  of 
related  variables.  Consider,  for  example,  a  table  containing  ten  rows  of 
numbers,  with  20  numbers  in  each  row.  There  are  200  numbers  in  the  table. 
How  would  you  like  it  if  you  had  to  assign  a  unique  name  to  each  of  the  200 
numbers?  It  would  be  far  simpler  to  give  the  entire  table  one  name  and 
identify  individual  numbers  within  the  table  by  their  table  locations.  That  is 
precisely  what  an  array  does. 

Arrays  can  have  one  or  more  dimensions.  An  array  with  a  single  dimen- 
sion is  equivalent  to  a  table  with  just  one  row  of  numbers.  The  dimension 
identifies  a  number  within  the  single  row.  An  array  with  two  dimensions 
yields  an  ordinary  table  with  rows  and  columns:  one  dimension  identifies  the 
row;  the  other  dimension  identifies  the  column.  An  array  with  three  dimen- 
sions yields  a  "cube"  of  numbers,  or  perhaps  a  stack  of  tables.  Four  or  more 
dimensions  yield  an  array  that  is  hard  to  visualize  but  is  mathematically  no 
more  complex  than  an  array  with  fewer  dimensions. 

Let  us  examine  arrays  in  detail.  A  single-dimension  array  element  has 
the  following  form: 

name(i) 

where 

name     is  the  variable  name  for  the  array.  Any  type  of  variable  name 
may  be  used. 

i  is  the  array  index  to  that  element;  /  must  start  at  0. 

A  single-dimension  array  called  A,  having  five  elements,  can  be  visualized  as 
follows: 


A(0) 
A(l) 
A(2) 
A(3) 
A(4) 


The  number  of  elements  in  the  array  is  equal  to  the  highest  index  number  plus 
1.  This  takes  array  element  0  into  account. 
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A  two-dimension  array  element  has  the  following  form: 

name(i,j) 

where 

name     is  the  variable  name  of  the  array 
/  is  the  column  index 

j  is  the  row  index 

A  two-dimension  string  array  called  A$,  having  two  column  elements  and 
three  row  elements,  might  be  visualized  as  follows: 


A$(0,0) 
A$(1,0) 
A$(2,0) 


A$(0,1) 
A$(l,l) 
A$(2,l) 


The  size  of  the  array  is  the  product  of  the  highest  row  dimension  plus  1 , 
multiplied  by  the  highest  column  dimension  plus  1.  For  this  string  array,  it  is 
3X2  =  6  elements. 

Additional  dimensions  can  be  added  to  the  array  by  using  the  form 

name(i,j,k, . . .) 

Arrays  of  as  many  as  11  elements  (index  0  to  10  for  a  single-dimension 
array)  may  be  used  routinely  in  C-128  BASIC.  Arrays  containing  more  than 
11  elements  need  to  be  specified  in  a  dimension  statement.  Dimension  state- 
ments are  described  later  in  this  chapter.  If  you  do  not  enter  the  subscript  for 
an  array  in  your  program,  it  will  be  treated  as  a  separate  variable  by  C-128 
BASIC.  This  can  lead  to  hard-to-find  bugs  in  your  program.  You  should  not 
exploit  this  distinction  in  your  programs:  other  languages  and  other  dialects 
of  BASIC  do  not  work  in  the  same  way.  This  technique  could  cause  confusion 
for  other  programmers  trying  to  read  your  code,  even  you,  should  you  later 
decide  you  had  mistakenly  left  out  the  subscript  and  try  to  fix  the  "error." 


BASIC  Commands 

Chapter  2  described  a  number  of  commands  that  can  be  entered  at  the 
keyboard  in  order  to  control  C-128  computer  operations.  RUN  is  one  such 
command.  All  commands  can  be  executed  as  BASIC  statements. 

You  are  unlikely  to  execute  commands  out  of  BASIC  statements  when 
you  first  start  writing  programs.  However,  when  you  start  writing  very  large 
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programs,  you  may  run  out  of  memory  space.  Then  you  must  break  a 
program  into  a  number  of  smaller  modules  and  execute  them  one  at  a  time. 

Reserved  Words 

All  of  the  character  combinations  that  define  a  BASIC  statement's  opera- 
tions, and  all  functions,  are  called  reserved  words.  Table  3-4  lists  the  C-128 
BASIC  reserved  words.  You  will  encounter  many  of  these  reserved  words  in 
this  chapter,  but  others  are  not  described  until  later  chapters. 


TABIE  3-4.  Reserved  Words 


Word 

Abbrev 

Word 

Abbrev 

Word 

Abbrev 

ABS 

A-B 

CONT 

♦FILTER 

F-I 

*APPEND 

A-P 

♦COPY 

CO-P 

FOR 

F-O 

ASC 

A-S 

COS 

FRE 

F-R 

ATN 

A-T 

DATA 

D-A 

FNXX 

*AUTO 

A-U 

♦DEC 

GET 

G-E 

♦BACKUP 

BA-C 

♦DCLEAR 

DCL-E 

♦GETKEY 

GETK-E 

*BANK 

B-A 

♦DCLOSE 

D-C 

GET# 

*BEGIN 

B-E 

DEF  FN 

GOSUB 

GO-S 

*BEND 

BE-N 

♦DELETE 

KDE-L 

♦G064 

*BLOAD 

B-L 

DIM 

D-I 

GOTO 

G-O 

*BOOT 

B-O 

♦DIRECTORY 

DI-R 

♦GRAPHIC 

G-R 

*BOX 

♦DLOAD 

D-L 

♦GSHAPE 

G-S 

*BSAVE 

B-S 

♦DO 

♦HEADER 

HE- A 

*BUMP 

B-U 

♦DOPEN 

D-O 

♦HELP 

♦CATALOG 

C-A 

♦DRAW 

D-R 

♦HEX 

H-E 

*CHAR 

CH-A 

♦DSAVE 

D-S 

IF 

CHR$ 

C-H 

♦DVERIFY 

D-V 

INPUT 

♦CIRCLE 

C-I 

♦EL 

INPUT# 

I-N 

CLOSE 

CL-0 

END 

♦INSTR 

IN-S 

CLR 

C-L 

♦ENVELOPE 

E-N 

INT 

CMD 

C-M 

♦ER 

♦JOY 

J-0 

♦COLLECT 

COLL-E 

♦ERRS 

E-R 

♦KEY 

K-E 

♦COLINT 

♦EXIT 

EX-I 

LEFTS 

LE-F 

♦COLLISION 

COL-L 

EXP 

E-X 

LEN 

♦COLOR 

COL-O 

♦FAST 

LET 

L-E 

♦CONCAT 

C-0 

♦FETCH 

F-E 

LIST 

L-I 

NOTE:  Keywords  marked  with  an  asterisk  (*)  are  C-128  mode  commands  only.  All  others  are  both  C-64  and 

C-128  mode  commands.  Dashes  indicate  use  of  the  SHIFT  key  at  that  point. 
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TABLE  3-4.  Reserved  Words  (continued) 


Word 

Abbrev 

Word 

Abbrev 

Word 

Abbrev 

LOAD 

L-O 

*D  UM  A  A/fTT 

DEM 

Kb-JN 

c  c 

♦LOCATE 

LO-C 

*  D  E\I  1  \  A  DCD 

DEM  T  T 

ilcCTA  CO 

C  T 

!S-  1 

LOG 

D  ECTAD  C 

Kb!S  1  (JKc 

D  C  C 

ST 

*LOOP 

LO-O 

*D  ECI  TA/f  C 

D  EC  IT 

c  t"  rr  d 
S  1  br 

CT  ET 

b  l  -b 

MID$ 

M-I 

E>  ETl  TDM 

Kb  1  U  KIN 

D  ~C  T 

Kb-  1 

STOP 

C"T  f^l 

♦MONITOR 

MO-N 

D  C 

K-U 

CTD  <T 

S  1  K3> 

CT  D 

!S  1  -K 

*MOVESHAPE 

KILrri  1  3> 

D  1 

K-J 

*  C  \\7  A  D 

*S  WAr 

C  \\7 

*MOVSPR 

*D  T  T  T  A/I 

KLU  M 

c  vc 

NEW 

RND 

D  XT 

K-JN 

TAB 

T-A 

NEXT 

N-E 

D  ETI  T  D  XT 

Kb  1  U  KJN 

D  ~C  T 

Kb- 1 

TAN 

ON 

D 

K-U 

*T^E  A  A  T)f\ 

*  I  bMrU 

T  IT 

1  -b 

OPEN 

O-P 

*  d  COD  ITE 

*K!SrKl  1  b 

DCD  D 

Kbr-K 

TI 

*  PAINT 

P-A 

D  T  TXT 
KUIN 

D    T  T 

K-U 

TI$ 

PEEK 

PE-E 

*  D  \I  / 1  XT      fW\  1 

*KW  UN  UUW 

D  \\J 

K- W 

TO 

*PEN 

P-E 

c  A\/r: 

C  A 

S-A 

♦TRAP 

T~  D 

1  -K 

PI 

ISL.-A 

*  1  KOrr 

TnA  TT 

1  K(J-r 

*PLAY 

P-L 

*>3UINUbK 

*  T  D  r\XT 

*  1  KUIN 

1  K-U 

POINTER 

*QCT>  ATrU 
^ISL^KAl  Cri 

*T  TXTTI  T 

*UIN  lib 

T  T  XT 
U-fN 

POKE 

PO-K 

C/^XT 

T  TC  D 
UiSK 

1  T  C 

POS 

\/A  T 
VAb 

*POT 

P-O 

♦SLEEP 

S-L 

VERIFY 

V-E 

PRINT 

? 

♦SLOW 

♦VOL 

V-O 

PRINT# 

P-R 

♦SOUND 

S-0 

WAIT 

W-A 

*RBUMP 

RB-U 

SPC 

♦WHILE 

W-H 

*RCLR 

R-C 

♦SPRCOLOR 

SPR-C 

♦WIDTH 

WI 

*RDOT 

R-D 

♦SPRDEF 

SPR-D 

♦WINDOW 

W 

READ 

RE-A 

♦SPRITE 

S-P 

♦XOR 

X 

♦RECORD 

R-E 

♦SPRSAV 

SPR-S 

REM 

SQR 

S-Q 

NOTE:  Keywords  marked  wi 

th  an  asterisk  (*)  are  C- 1 28  mode  commands  only.  All  others  are  both  C-64  and 

C-128  mode  commands.  Dashes  indicate  use  of  the  SHIFT  key  at  that  point. 

When  executing  BASIC  programs,  the  C-128  computer  scans  every 
BASIC  statement,  seeking  out  any  character  combinations  that  make  up 
reserved  words.  (The  only  exceptions  are  text  strings  enclosed  in  quotes.)  This 
can  cause  trouble  if  a  reserved  word  is  embedded  anywhere  within  a  variable 
name.  The  C-128  computer  cannot  identify  a  variable  name  by  its  location  in  a 
BASIC  statement.  Therefore,  you  should  be  very  careful  to  keep  reserved 
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words  out  of  your  variable  names.  This  is  particularly  important  with  the 
short  reserved  words  that  can  easily  slip  into  a  variable  name. 

BASIC  Word  Abbreviations 

As  you  may  remember,  the  BASIC  statement  PRINT  can  always  be  entered 
from  the  keyboard  with  the  abbreviation  ?.  This  abbreviation  is  expanded  by 
the  C-128  BASIC  interpreter  to  the  full  word  PRINT. 

Most  BASIC  commands,  statements,  and  functions  can  be  abbreviated 
to  the  first  two  characters  of  the  keyword,  with  the  second  character  entered  in 
shifted  mode.  With  the  C-128  normal  character  set  (that  is,  uppercase  or 
graphic  characters),  the  second  character  appears  as  a  graphic  character.  For 
example,  the  abbreviation  for  LIST  appears  as 

L 
II 

C-128  BASIC  makes  no  distinction  between  the  two  abbreviations;  either  one 
is  expanded  to  the  word  LIST 

If  a  two-letter  abbreviation  is  ambiguous  (does  ST  mean  STEP  or 
STOP?),  the  two-letter  abbreviation  is  assigned  to  the  most  frequently  used 
keyword,  and  the  other  word  (or  words)  is  either  not  abbreviated  or  is 
abbreviated  using  the  first  three  characters,  with  the  third  entered  in  shifted 
mode.  For  STEP  and  STOP,  for  example,  STOP  is  abbreviated  as 

sT 

SI 

STEP  is  abbreviated  as 

fttE 

S7~ 

To  abbreviate  STEP,  type  an  unshifted  (uppercase)  S,  an  unshifted  T,  and  a 
shifted  E. 

The  following  sample  input  lines  use  two-  and  three-letter  abbreviations 
wherever  possible.  All  abbreviated  words  are  expanded  to  the  full  spelling 
when  you  list  the  programs. 

■+  Press  shift  C-  for  lower  case. 

10  IE  3=10 

20  b»a  J.N  14+*X<2) 

30  dl  c<5> 

40  fO  i*0  to  S 

50  rE  c(i> 
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60  YiE 

70  dfl  1,6,2,4, 10,5, 16 
80  reS 
90  ©H 

II  

10  let  a«10 

20  b«A  and  14+efcP (2) 

30  dim<5) 

40  for  i«0  to  5 

50  read  c<i> 

60  rifrxt 

70  data.  1,6,2,4,  10,5, 16 
80  re-store 
90  end 


-LIST  the  program. 


BASIC  statements  are 
not  abbreviated. 


-Press  shift  Cs  for  upper  case. 


After  pressing  the  SHIFT  key  and  the  Commodore  key  simultaneously,  you 
will  see  the  abbreviations  displayed  with  graphics  in  the  place  of  the  shifted 
characters.  The  expanded  listing  will  display  uppercase  letters. 

Refer  to  Table  3-4:  the  expansions  from  abbreviations  for  the  two 
functions  SPC  and  TAB  include  the  left  parenthesis.  This  means  that  if  you 
use  the  abbreviation  for  either  of  these,  you  must  not  type  in  the  left  parenthe- 
sis. For  example, 

10  ?&P<5> 

expands  to 

10  Print  *Pca5) 


A  syntax  error  will  result  from  two  left  parentheses.  The  correct  sequence  to 
key  in  is 

10  ?sP5) 

This  parenthesis  rule  applies  only  to  the  SPC  and  TAB  functions,  and  is 
a  format  inconsistency  you  will  have  to  watch  for  when  abbreviating  these 
function  names.  For  all  other  functions,  you  key  in  both  parentheses.  For 
example, 

10  ?rN<l) 


BASIC  Statements 

The  operation  performed  by  a  BASIC  statement  is  specified  by  using  reserved 
words  (see  Table  3-4). 

Statements  are  not  described  in  detail  in  this  chapter,  since  it  introduces 
you  to  programming  concepts,  stressing  the  way  statements  are  used.  Refer  to 
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Appendixes  E  and  F  for  complete  descriptions  of  all  statements  recognized  by 
C-128  BASIC. 

Remarks 

The  first  statement  you'll  be  looking  at  is  the  only  BASIC  statement  that  the 
computer  will  ignore:  the  remark.  If  the  first  three  characters  of  a  BASIC 
statement  are  REM,  the  computer  ignores  the  statement  entirely.  So  why 
include  such  a  statement?  The  answer  is  that  remarks  make  your  program 
easier  to  read. 

If  you  write  a  short  program  with  five  or  ten  statements,  you  will 
probably  have  little  trouble  remembering  what  the  program  does  —  unless 
you  leave  it  around  for  six  months  and  then  try  to  use  it  again.  If  you  write  a 
longer  program  with  100  or  200  statements,  you  are  quite  likely  to  forget 
something  important  the  very  next  time  you  use  the  program.  After  you  have 
written  dozens  of  programs,  you  cannot  possibly  remember  each  one  in 
detail.  The  solution  to  this  problem  is  to  document  your  program  by  includ- 
ing remarks  that  describe  what  the  various  parts  of  the  program  do. 

Good  programmers  usually  use  plenty  of  remarks  in  all  of  their  programs. 
All  of  this  chapter's  program  examples  include  remarks  that  describe  what  is 
going  on,  simply  to  get  you  into  the  habit  of  doing  the  same  thing  yourself. 

Remark  statements  have  line  numbers  like  any  other  statements.  A 
remark  statement's  line  number  can  be  used  like  any  other  statement's  line 
number. 

Assignment  Statements 

Assignment  statements  let  you  assign  values  to  variables.  You  will  encounter 
assignment  statements  frequently  in  every  type  of  BASIC  program.  Here  are 
some  examples  of  assignment  statements. 

90  REM  INITIRLIZE  VflRIRBLE  X 
100  LET  X*3.24 

In  statement  100,  floating  point  variable  X  is  assigned  the  value  3.24. 
150  X<3.24 

This  is  equivalent  to  statement  100.  The  LET  is  optional  in  all  assignment 
statements. 

215  R$»"RLSG  RAN" 

Here,  the  string  variable  A$  is  assigned  the  two  text  words  ALSO  RAN. 
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Notice  that  the  first  assignment  statement  (line  100)  begins  with  the  word 
LET,  but  the  other  two  don't.  Originally,  all  assignment  statements  had  to 
start  with  LET.  The  idea  was  that  the  computer  could  identify  the  type  of 
statement  by  looking  at  the  first  word.  Today,  all  but  a  few  dialects  of  BASIC 
have  dropped  this  requirement.  Although  LET  is  not  required  by  C-128 
BASIC,  it  is  still  a  reserved  word  and  cannot  appear  in  a  variable  name. 

Here  are  three  statements  that  assign  values  to  array  variable  DP$(I), 
which  you  encountered  earlier  in  the  discussion  of  arrays. 

200  REM  DPi(I)  IS  THE  DAIRY  PRODUCTS  SHOPPING  LIST 

VRRIRBLE 
210  DPt^^'MILK" 
220  DP*a>«"  CREAM" 
230  DP*<2>*MC0TTAGE  CHEESE" 

Remember,  you  can  put  more  than  one  statement  on  a  single  line.  The  three 
DP$  assignments  could  be  placed  on  a  single  line  as  follows: 

200  REM  DPtCI)  IS  THE  DAIRY  PRODUCTS  SHOPPING  LIST 
VARIABLE 

210  DP*  <  0  )  «  "  M I LK  "  :  DP*  <  1 )  *  "  CREAM  "  DP*  <  2  )  «  "  COTTAGE  CHEESE " 

A  colon  must  separate  adjacent  statements  appearing  on  the  same  line. 

Assignment  statements  can  include  any  of  the  arithmetic  or  relational 
operators  described  earlier  in  this  chapter,  as  shown  here: 

90  REM  THIS  IS  A  DUMB  WAV  TO  ASSIGN  A  VALUE  TO  V 
100  V*3. 24+7. 96/8. 5 

This  statement  assigns  the  value  4.17647059  to  floating  point  variable  V.  It  is 
equivalent  to  these  three  statements: 

90  REM  X  AND  V  NEED  TO  BE  INITIALIZED  SEPARATELY  FOR 

LATER  USE 
100  X«7.96 
110  Y*8.5 
120  V=3.24+X/Y 

These  statements  could  be  written  on  one  line  as  follows: 

100  X»?.96:V=8.5:V=3.24-fX/V 

Here  are  assignment  statements  that  perform  the  Boolean  operations 
described  earlier  in  this  chapter. 

90  REM  THESE  EXAMPLES  WERE  DESCRIBED  EARLIER  IN 

THE  CHAPTER 
100  AX=43  AND  137 
200  BK=43  OR  137 
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The  following  example  shows  how  string  concatenation  can  be  used  to 
assign  a  value  to  a  string  variable: 

100  V$»" COTTAGE " 

200  W*«" CHEESE" 

300  DP$<2)"V*+"  "+W$ 

400  REM  DP$<2)  IS  ASSIGNED  THE  STRING  VALUE 
"COTTAGE  CHEESE" 

DATA  AND  READ  STATEMENTS 

When  some  variables  need  data  assignments,  the  DATA  and  READ 
statements  should  be  used  rather  than  the  LET  statement.  Consider  the 
following  example: 

5  REM  INITIALIZE  ALL  PROGRAM  VARIABLES 
10  DATA  10,20,-4, 16E6 
20  READ  A,B,C,D 

The  statement  on  line  10  lists  four  numeric  data  values.  These  four  values  are 
assigned  to  four  variables  on  line  20.  After  the  statements  on  lines  10  and  20 
have  been  executed,  A=10,  B=20,  C=-4,  and  D=16X106. 

If  you  have  one  or  more  DATA  statements  in  your  program,  you  can 
visualize  them  as  building  a  "column"  of  numbers.  For  example,  a  DATA 
statement  that  contains  a  list  of  ten  numbers  would  build  a  ten-entry  column. 
Two  DATA  statements,  each  with  a  list  of  five  data  items,  would  build  exactly 
the  same  column.  This  may  be  illustrated  as  follows: 


The  first  READ  statement  executed  in  a  program  starts  at  the  first 
column  entry,  assigning  each  value  to  corresponding  variables  named  in  the 
READ  statement.  The  second  and  subsequent  READ  statements  take  values 
from  the  column,  starting  at  the  point  where  the  previous  READ  statement 
left  off.  This  may  be  illustrated  as  follows. 


10  DATA  10,  20,  30,  40,  50,  60,  70,  80,  90,  100 


First  column  entry — ►/  10 
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10  DATA  10,  20,  30,  40,  50,  60,  70,  80,  90,  100 


RESTORE  STATEMENT 

At  any  time,  you  can  send  the  pointer  back  to  the  beginning  of  the 
numeric  column  by  executing  a  RESTORE  statement.  Here  is  an  example  of 
the  use  of  RESTORE. 

10  DATA  10,  20,  30,  40,  50,  60,  70,  80,  90,  100 
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Dimension  Statement 

C-128  BASIC  normally  assumes  that  a  variable  has  a  single  dimension,  with 
index  values  of  0  through  10.  This  generates  an  11 -element  array.  If  you  want  a 
single  dimension  with  more  than  or  fewer  than  11  elements,  then  you  must 
include  the  array  variable  in  a  dimension  (DIM)  statement.  You  also  must 
include  the  array  in  a  dimension  statement  if  it  has  two  or  more  dimensions, 
no  matter  what  number  of  elements  it  has.  The  following  example  provides 
dimensions  for  one-dimension  array  variables  MPS,  FV$,  and  DPS.  These 
variables  were  used  in  the  earlier  discussion  of  arrays. 

DIM  MP*(5>,FV*C3>JDP*(2> 

The  two-dimension  grocery-list  variable,  GL$,  would  be  dimensioned  as 
follows: 

DIM  GL#<3i5> 

A  DIM  statement  can  provide  dimensions  for  any  number  of  variables, 
providing  the  statement  fits  within  an  80-character  line. 

The  number  or  numbers  following  a  variable  name  in  a  DIM  statement 
are  equal  to  the  largest  index  value  that  can  occur  in  that  particular  index 
position.  But  remember,  indexes  begin  at  0.  Therefore,  MP$(5)  dimensions 
the  variable  MPS  to  have  six  values,  not  five,  since  indexes  0,  1,  2,  3,  4,  and  5 
will  be  allowed.  GL$(3,5),  likewise,  specifies  a  two-dimension  variable  with  24 
entries,  since  the  first  dimension  can  have  values  0,  1,2,  and  3,  while  the 
second  dimension  can  have  values  0  through  5. 

Once  you  have  declared  an  array  variable  in  a  DI M  statement,  you  must 
subsequently  reference  the  variable  with  the  specified  number  of  subscripts; 
each  subscript  must  have  a  value  between  0  and  the  number  specified  in  the 
DIM  statement.  If  any  of  these  syntax  rules  are  broken,  you  will  get  a  syntax 
error. 

Branch  Statements 

Statements  within  a  BASIC  program  normally  execute  in  ascending  line- 
number  order.  This  execution  sequence  was  explained  in  the  discussion  of  line 
numbers  earlier  in  this  chapter.  Branch  statements  change  this  execution 
sequence. 
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GOTO  STATEMENT 

GOTO  is  the  simplest  branch  statement.  It  allows  you  to  specify  the 
statement  that  will  be  executed  next.  Consider  the  following  example: 


20  A=4.37 

30  GOTO  100 

40 

50 

60 

70 

80 

90 

100 

110 


The  statement  on  line  20  is  an  assignment  statement;  it  assigns  a  value  to 
floating  point  variable  A.  The  next  statement  is  a  GOTO;  it  specifies  that 
program  execution  must  branch  to  line  100.  Therefore,  the  instruction 
execution  sequence  surrounding  this  part  of  the  program  will  be  line  20,  then 
line  30,  and  then  line  100. 

Of  course,  some  other  statement  should  branch  back  to  line  40.  Otherwise 
the  statement  on  line  40  will  never  be  executed  by  program  logic,  as  illustrated 
in  the  example. 

You  can  branch  to  any  line  number,  even  if  the  line  contains  nothing  but  a 
remark.  However,  the  computer  ignores  the  remark,  so  the  effect  is  the  same 
as  branching  to  the  next  line.  For  example,  consider  the  following  branch: 


78-  REM  THERE  IS  fl  REMARK *  AND 
80' NOTHING  ELSE  ON  THIS  LINE 


,30;GOTO  70 
40 
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The  program  branches  from  line  30  to  line  70.  There  is  nothing  but  a  remark 
on  line  70;  so  the  computer  moves  on  to  line  80,  executing  the  statement  on 
this  line.  Even  though  you  can  branch  to  a  remark,  you  might  as  well  branch 
to  the  next  line.  This  may  be  illustrated  as  follows: 

20^*4.37 

30>OOTO  80 
/40 

50 
V  60 

\70  REM  THERE  IS  R  REMRRK,  AND 
80  NOTHING  ELSE  OH  THIS  LINE 
90 


COMPUTED  GOTO  STATEMENT 

There  is  also  a  computed  GOTO  statement  that  lets  program  logic 
branch  to  one  of  two  or  more  different  line  numbers,  depending  on  the 
current  value  of  a  variable.  Consider  the  following  illustration. 


A%=  3 


The  statement  on  line  40  is  a  computed  GOTO.  When  this  statement  executes, 
the  program  will  branch  to  statement  10  if  variable  A%=  1 ,  to  statement  70  if 
variable  A%=  2,  or  to  statement  150  if  A%=  3.  If  A%  has  any  value  other  than 
1,  2,  or  3,  the  program  will  not  branch.  Notice  that  variable  A%  is  assigned  a 
value  in  statement  30.  The  value  assigned  to  A%  depends  on  the  current  value 
of  variable  B%.  The  illustration  does  not  show  how  variable  B%  is  computed, 
but  as  long  as  B%  has  a  value  of  3, 4,  or  5,  the  statement  on  line  40  will  cause  a 
branch. 
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To  test  the  computed  GOTO  statement,  key  in  the  following  program: 

10  BK=4 

20  PRINT  B/i 

30  flX«BK~2 

40  ON  R/iGOTO  10,70,  150 

70  PRINT  B'/. 

80  BB«5 

90  GOTO  30 

150  PRINT  BK 

160  BH«3 

170  GOTO  20 

Now  execute  this  program  by  typing  RUN  on  any  blank  line.  Do  not  type 
RUN  on  a  line  that  is  already  displaying  something.  If  you  do,  you  will  get  a 
syntax  error  and  the  program  will  not  be  executed. 

Can  you  account  for  the  sequence  in  which  digits  are  displayed?  Try 
rewriting  the  program  so  that  each  number  is  displayed  once,  in  the  sequence 
345345345.... 

Control  Statements 

In  every  program,  the  sequence  in  which  statements  are  executed  is  every  bit 
as  important  as  the  statements  themselves.  C-128  BASIC  has  several 
statements  that  control  the  way  a  program  executes  —  hence  they  are  called 
control  statements. 

Control  statements  redirect  the  execution  sequence  of  a  program.  Some 
control  statements  choose  one  of  many  paths  program  logic  can  take;  others 
execute  several  statements  a  specified  number  of  times. 

FOR-NEXT  Statement 

GOTO  and  computed  GOTO  statements  let  you  create  any  type  of  statement 
execution  sequence  that  your  program  logic  requires.  But  suppose  you  want 
to  reexecute  an  instruction  (or  a  group  of  instructions)  many  times.  For 
example,  suppose  array  variable  A(I)  has  100  elements  and  each  element 
needs  to  be  assigned  a  value  ranging  from  0  to  99.  Writing  a  hundred 
assignment  statements  would  be  tedious.  It  is  far  simpler  to  reexecute  one 
statement  100  times.  This  can  be  done  with  the  FOR  and  NEXT  statements. 

10  DIM  fl<99) 

20  FOR  1-0  TO  99  STEP  1 

30  PKI>*I 

40  NEXT  I 

Statements  between  FOR  and  NEXT  execute  repeatedly.  In  this  case,  a 
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single  assignment  statement  appears  between  FOR  and  NEXT,  so  this  single 
statement  is  reexecuted  repeatedly. 

To  see  how  FOR-NEXT  loops  work,  you  will  display  the  A(I)  values 
created  within  the  loop.  Key  in  the  following  program: 

10  DIM  AC99) 

20  FOR  1*0  TO  99  STEP  1 

30  fl<I)«I 

35  PRINT  AC  I) 

40  NEXT  I 

50  REM  IF  VOU  HAVE  fl  OOTO  STATEMENT  THAT  BRANCHES  TO 
ITSELF,  THE 

70  REM  COMPUTER  EXECUTES  AN  ENDLESS  LOOP:   in  EFFECT, 

IT  WAITS 
90  GOTO  90 

Now  type  RUN.  One  hundred  numbers  display,  starting  at  0  and  ending  at  99. 
Press  the  STOP  key  to  terminate  program  execution. 

Statements  between  FOR  and  NEXT  reexecute  the  number  of  times 
specified  by  the  index  value  directly  after  FOR.  In  this  example,  the  index 
variable  is  1. 1  increases  in  value  from  0  to  99  in  increments  of  1 .  The  first  time 
the  assignment  statement  is  executed,  I  will  equal  0  and  the  assignment 
statement  on  line  30  will  be  executed  as  follows: 

30  A<0)=0 

I  increases  by  the  step,  or  increment,  size,  which  is  specified  on  line  20  as  1 .  I 
therefore  equals  1  the  second  time  the  assignment  statement  on  line  30  is 
executed.  The  assignment  statement  has  effectively  become 

30  fl<l)-l 

I  continues  to  increment  by  the  specified  step  value  until  the  maximum  value 
of  99  is  reached  or  exceeded. 

The  step  value  does  not  have  to  be  1;  it  can  have  any  value.  Change  the 
step  value  to  5  on  line  20  and  reexecute  the  program.  Now  the  assignment 
statement  is  executed  only  20  times,  since  incrementing  I  by  5  nineteen  times 
will  take  it  to  95.  (The  twentieth  increment  will  take  it  to  100,  which  is  more 
than  the  maximum  value  of  99.) 

The  step  size  does  not  have  to  be  positive.  But  if  the  step  size  is  negative, 
the  initial  value  of  I  must  be  larger  than  the  final  value  of  I.  For  example,  if  the 
step  size  is  —  1  and  you  want  to  initialize  100  elements  of  A(I)  with  values 
ranging  from  0  to  99,  then  you  would  have  to  rewrite  the  statement  on  line  20 
as  follows: 
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18  DIM  R<99) 

20  FOR  1*0  TO  99  STEP  -1 

30  R<I)=I 

35  PRINT  flCDJ 

40  NEXT  I 

80  GOTO  30 

Execute  this  program  to  test  the  negative  step. 

In  this  example,  the  initial  and  final  values  for  I  and  the  step  size  are 
treated  as  integers.  You  must,  however,  represent  these  three  values  using 
floating  point  variables  or  expressions.  Expressions  will  be  evaluated  to  a 
floating  point  result.  The  floating  point  result  will  be  converted  to  an  integer 
according  to  the  round-off  rules  described  earlier  in  this  chapter. 

Because  the  round-off  rules  can  cause  problems,  you  are  strongly  urged 
to  use  beginning  values,  ending  values,  and  step  sizes  as  integers.  Do  not  use 
expressions,  since  this  unnecessarily  complicates  the  program.  If  you  must 
calculate  one  of  these  values,  it  is  simpler  and  faster  to  do  so  in  a  separate 
statement. 

If  the  step  size  is  1  (which  is  frequently  the  case),  you  do  not  have  to 
include  a  step  size  definition.  In  the  absence  of  any  definition,  C-128  BASIC 
assumes  a  step  size  of  1 .  Therefore,  the  statement  on  line  20  could  be  rewritten 
as  follows: 

10  DIM  fl<99> 

15  REM  USE  R  STEP  SIZE  OF  1 

20  FOR  I»0  TO  99 

30  RCI)»I 

33  PRINT  RCI); 

40  NEXT  I 

80  GOTO  80 

Also,  you  do  not  need  to  specify  the  index  variable  in  the  NEXT 
statement.  But  if  you  do,  it  will  make  your  program  easier  to  read. 

NESTED  LOOPS 

The  FOR-NEXT  structure  is  referred  to  as  a  program  loop,  since 
statement  execution  loops  from  FOR  to  NEXT  and  back  to  FOR.  This  loop 
structure  is  very  common;  almost  every  BASIC  program  that  you  write  will 
include  one  or  more  such  loops.  Loops  are  so  common  that  they  are 
frequently  nested.  The  statement  sequence  occurring  between  FOR  and 
NEXT  can  be  of  any  length;  it  can  run  to  tens  or  even  hundreds  of  statements. 
And  within  these  tens  or  hundreds  of  statements,  additional  loops  may  occur. 
The  following  illustration  shows  a  single  level  of  nesting. 
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10  DIM  A<99> 

20  FOR  I»0  TO  99 

30  A<I)«I 

40  REM  DISPLflV  ALL  VALUES  OF  AC  I)  ASSIGNED  THUS  FAR 

50  FOR  J*0  TO  I 

£0  PRINT  ACJ) 

70  NEXT  J 

80  NEXT  I 

90  GOTO  90 

Complex  loop  structures  appear  frequently,  even  in  relatively  short 
programs.  Here  is  an  example  showing  the  FOR  and  NEXT  statements,  but 
none  of  the  intermediate  statements. 


50  FOR  1=1  TO  10 

60  FOR  X=25  TO  347  STEP  3 


100  FOR  A=9  TO  0  STEP  - 1 


140  NEXT  A 

200  FOR  B=25  TO  100  STEP  5 


280  NEXT  B 
300  NEXT  X 


500  FOR  V=  1  TO  20  STEP  2 


600  FOR  P=  10  TO  20 


650  NEXT  P 
700  NEXT  V 
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1000  FOR  Z=l  TO  10 


1090  NEXT  Z 
1200  NEXT  I 

The  outermost  loop  uses  index  I;  it  contains  three  nested  loops  that  use 
indexes  X,  Y,  and  Z.  The  first  loop  contains  two  additional  loops  that  use 
indexes  A  and  B.  The  second  loop  contains  one  nested  loop  using  index  P. 
The  third  loop  contains  no  nested  loops.  Each  nested  loop  must  have  a 
different  index  variable  name.  Statement  execution  sequences  may  be 
illustrated  as  follows: 


Loop  structures  are  easy  to  visualize  and  use.  There  is  only  one  common 
error  to  watch  out  for:  do  not  terminate  an  outer  loop  before  you  terminate  an 
inner  loop.  For  example,  the  following  loop  structure  is  illegal: 

IR  1-1  TO  10 
f  X«25  TO  347  STEP  3 
JEXT  I 
4EXT  X 
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If  you  do  not  include  the  index  variable  in  the  NEXT  statement,  program 
logic  will  automatically  terminate  loops  correctly,  since  there  is  only  one 
possible  correct  loop  termination  each  time  a  NEXT  statement  is  encountered. 

Every  program  must  have  the  same  number  of  FOR  and  NEXT  state- 
ments, since  every  loop  must  begin  with  a  FOR  statement  and  end  with  a 
NEXT  statement.  For  example,  suppose  there  are  two  FOR  statements  but 
only  one  NEXT  statement.  The  second  FOR  statement  constitutes  an  inner 
loop  that  will  execute  correctly.  But  the  outer  loop  has  no  NEXT  statement  to 
terminate  it,  so  the  program  will  execute  incorrectly.  Too  many  NEXT 
statements  will  also  cause  a  syntax  error. 


Subroutine  Statements 

Once  you  start  writing  programs  that  are  more  than  a  few  statements  long, 
you  will  quickly  find  short  routines  that  are  used  repeatedly.  For  example, 
suppose  you  have  an  array  variable  (such  as  A(I))  that  is  reinitialized  fre- 
quently at  different  points  in  your  program.  Would  you  simply  repeat  the 
three  instructions  that  constitute  the  FOR-NEXT  loop  described  earlier? 
Since  there  are  only  three  instructions,  you  may  as  well  do  so. 

However,  suppose  you  have  to  initialize  the  array  and  then  execute  10  or 
11  instructions  that  process  array  data  in  some  fashion.  If  you  had  to  use  this 
loop  many  times  within  one  program,  rewriting  10  to  15  statements  each  time 
you  wished  to  use  the  loop  would  take  time  —  but  more  important,  it  would 
waste  a  good  deal  of  computer  memory.  This  may  be  illustrated  as  follows: 

Start  of  program  — 


Repeated  routine 


etc. 


To  solve  this  problem,  you  could  separate  out  the  repeated  statements  and 
branch  to  them.  This  group  of  statements  is  referred  to  as  a  subroutine. 

But  a  problem  arises.  Branching  from  your  program  to  the  subroutine  is 
simple  enough,  since  the  subroutine  starts  at  a  given  line  number.  However, 
where  do  you  branch  back  to  when  the  subroutine  ends?  You  could  execute  a 
GOTO  statement  whenever  you  wish  to  branch  to  a  subroutine. 
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Arbitrarily  selected 
line  numbers 


Start  of  program- 


10 


Subroutine 


100  GOTO  2000---""  St. 

'  / 


2000 


110 


190  GOTO  2000  ' 
200 


// 

/  / 


250  GOTO  2000 
260 


480  GOTO  2000 
500 


/  / 
/  / 
/  / 
/  / 
/ 

/ 


/ 


2150 


-start 


— end 


N 

\ 

A   \/ 

v  A 

Return  ✓ 


where? 


etc. 


A  GOSUB  statement  branches  in  the  same  way  as  a  GOTO,  but  it 
remembers  the  line  number  to  which  it  should  return.  This  is  illustrated  in  the 
following  section. 

GOSUB  STATEMENT 

Here  is  an  illustration  of  the  steps  of  a  GOSUB  statement. 


Subroutine 


110  GOSUB  2000 
110 


Remember 
110 


2000  t 
4 


2150  RETURN- 
\ 


start 


-  end 
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The  RETURN  statement  causes  a  branch  back  to  the  line  number  that  the 
GOSUB  statement  remembered.  The  three-statement  loop  that  initializes 
array  A(I),  if  converted  into  a  subroutine,  would  appear  as  follows: 


10  REM  MR IN  PROGRAM 

20  REM  VOU  CRN  DIMENSION  R  SUBROUTINE'S  VARIABLE  IN 
30  REM  THE  MAIN  PROGRAM.     IT  IS  R  GOOD  IDEA  TO  DIMENSION 
50  REM  ALL  VARIABLES  AT  THE  START  OF  THE  MAIN  PROGRAM. 
60  DIM  A<99> 
70  GOSUB  2000 

80  REM  DISPLRV  SOMETHING  TO  PROVE  THE  RETURN  OCCURRED 

90  PRINT  "RETURNED" 

100  GOTO  100 

2000  REM  SUBROUTINE 

2010  FOR  1-0  TO  99 

2020  RCI)«I 

2030  PRINT  fl<I); 

2040  NEXT  I 

2050  RETURN 


NESTED  SUBROUTINES 

Subroutines  can  be  nested:  a  subroutine  can  itself  branch  to,  or  call, 
another  subroutine,  which  in  turn  can  call  a  third  subroutine,  and  so  on.  You 
do  not  have  to  do  anything  special  in  order  to  use  nested  subroutines.  Simply 
branch  to  the  subroutine  with  a  GOSUB  statement;  each  subroutine  ends 
with  a  RETURN  statement.  C-128  BASIC  will  remember  the  correct  line 
number  for  each  nested  return.  The  following  program  illustrates  nested 
subroutines: 


10  REM  MR IN  PROGRAM 

20  REM  VOU  CRN  DIMENSION  R  SUBROUTINE'S  VARIABLE  IN 
30  REM  THE  MR IN  PROGRAM.     IT  IS  R  GOOD  IDEA  TO  DIMENSION 
50  REM  ALL  VARIABLES  AT  THE  START  OF  THE  MAIN  PROGRAM. 
£0  DIM  A<99> 
70  GOSUB  2000 

80  REM  DISPLRV  SOMETHING  TO  PROVE  THE  RETURN  OCCURRED 
90  PRINT" RETURNED" 
100  GOTO  100 

2000  REM  FIRST  LEVEL  SUBROUTINE 

2010  FOR  I»0  TO  99 

2020  R(D»I 

2030  GOSUB  3000 

2040  NEXT  I 

2050  RETURN 

3000  REM  NESTED  SUBROUTINE 
3010  PRINT  fl(I) 
3020  RETURN 


This  program  moves  the  PRINT  A(I)  statement  out  of  the  subroutine  and 
puts  it  into  a  nested  subroutine.  Nothing  else  changes. 
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COMPUTED  GOSUB  STATEMENT 

Since  GOTO  and  GOSUB  statement  logic  is  very  similar,  it  will  not  come 
as  any  surprise  that  there  is  a  computed  GOSUB  statement  akin  to  the 
computed  GOTO  statement.  The  computed  GOSUB  statement  allows  you  to 
branch  to  one  of  two  or  more  subroutines,  depending  on  the  value  of  an 
index.  Consider  the  following  statement: 

90 

100  OH  R  GOSUB  1800,500,5800,2300 
110 

When  the  statement  on  line  100  is  executed,  if  A=  1  the  subroutine  beginning 
at  line  1000  is  called.  If  A=  2,  the  subroutine  beginning  at  line  500  is  called.  If 
A=3,  the  subroutine  beginning  at  line  5000  is  called.  If  A=4,  the  subroutine 
beginning  at  line  2300  is  called.  If  A  has  any  value  other  than  1 ,  2,  3,  or  4,  the 
program  will  merely  continue  executing  at  line  110.  The  computed  GOSUB 
statement  remembers  the  next  line  number  (in  this  case,  110).  It  does  not 
matter  which  of  the  subroutines  is  called;  the  called  subroutine's  RETURN 
statement  will  branch  back  to  the  stored  line  number  (in  this  case,  110). 

You  can  nest  computed  GOSUB  statements  just  as  you  can  nest  standard 
GOSUB  statements. 

IF-THEN  Statement 

The  arithmetic  and  relational  operators  described  earlier  in  this  chapter  are 
frequently  used  in  IF-THEN  statements.  This  gives  a  BASIC  program 
decision-making  capabilities.  You  enter  any  expression  following  IF.  If  the 
expression  is  true,  the  statement  or  statements  following  THEN  are  executed. 
However,  if  the  expression  is  false,  the  statement  or  statements  following 
THEN  are  not  executed.  Here  are  three  simple  examples  of  IF-THEN 
statements. 

10  IF  fl»B+5  THEN  PRINT  MSG1 

40  IF  CC$<"tt"  THEN  IN=0 

50  IF  Q< 14  RND  MOM1  GOTO  66 

The  statement  on  line  10  causes  a  PRINT  statement  to  be  executed  if  the 
value  of  floating  point  variable  A  is  five  more  than  the  value  of  floating  point 
variable  B.  The  PRINT  statement  will  not  be  executed  otherwise.  The  state- 
ment on  line  40  sets  floating  point  variable  IN  to  0  if  string  variable  CC$  is  any 
letter  of  the  alphabet  in  the  range  A  through  L.  The  statement  on  line  50 
causes  program  execution  to  branch  to  line  66  if  floating  point  variable  Q  is 
less  than  14  and  floating  point  variable  M  is  not  equal  to  floating  point 
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variable  Ml.  Otherwise,  program  execution  will  continue  with  the  statement 
on  the  next  line  (GOTO  can  substitute  for  THEN). 

If  you  do  not  understand  the  evaluation  of  expressions  following  IF,  refer 
to  the  discussion  of  these  expressions  at  the  beginning  of  this  chapter. 

Input/Output  Statements 

There  are  a  variety  of  BASIC  statements  that  control  the  transfer  of  data  to 
and  from  the  computer.  These  are  collectively  referred  to  as  input  I  output 
statements.  The  simplest  input/  output  statements  control  data  input  from  the 
keyboard  and  data  output  to  the  display.  There  are  also  more  complex 
input /  output  statements  that  control  data  transfer  between  the  computer  and 
peripheral  devices  such  as  cassette  units,  diskette  units,  and  printers.  These 
more  complex  input/ output  statements  are  described  in  Chapter  8. 

Since  you  have  already  encountered  the  PRINT  statement,  this  state- 
ment will  be  discussed  first. 

PRINT  STATEMENT 

You  can  use  the  word  PRINT  or  a  question  mark  to  create  a  PRINT 
statement. 

Why  use  PRINT  instead  of  DISPLAY  or  some  abbreviation  of  the  word 
DISPLAY?  The  answer  is  that  in  the  early  sixties,  when  the  BASIC  pro- 
gramming language  was  being  created,  displays  were  very  expensive  and 
generally  unavailable  on  medium-  or  low-cost  computers.  The  standard 
computer  terminal  had  a  keyboard  and  a  printer.  Information  was  printed 
where  today  it  is  displayed;  hence,  the  use  of  the  word  "print"  to  describe  a 
statement  that  causes  a  display. 

The  PRINT  statement  will  display  any  data.  Text  must  be  enclosed  in 
quotes.  For  example,  the  following  statements  will  display  the  single  word 
TEXT: 

10  PRINT  "TEXT" 

or 

10  ?M  TEXT 11 

To  display  a  number  or  variable  name,  you  place  the  number  or  name 
after  PRINT,  as  follows: 

10  RK*10 
20  ?5,fl/i 

The  statement  at  line  20  displays  the  number  5  and  then  the  number  10  on  the 
same  line. 
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You  can  display  a  mixture  of  text  and  numbers  by  listing  the  information 
to  be  displayed  after  PRINT.  Use  commas  to  separate  individual  items.  The 
following  PRINT  statement  displays  the  words  ONE,  TWO,  THREE, 
FOUR,  and  FIVE,  followed  by  the  numeral  for  each  number: 

10  ?MONE" , 1 j  "TWO" , 2, "THREE" , 3, "FOUR" ,4, "FIVE" , 5 

If  you  separate  variables  with  commas,  then  the  C-128  computer  automati- 
cally assigns  1 1  character  spaces  for  each  variable  displayed.  Try  executing  the 
statement  in  immediate  mode  to  prove  this  to  yourself.  If  you  want  the  display 
to  remove  the  empty  spaces,  separate  the  variables  with  semicolons,  as 
follows: 

10  PRINT  "ONE"  ;  1  j  "TWO" ;  2;  "THREE"  ;  3;  "FOUR"; 4;  "FIVE";  5 

Enter  this  statement  in  immediate  mode  and  display  it  to  see  how  the 
semicolon  works. 

A  PRINT  statement  automatically  advances  to  the  next  line  of  the 
display  unless  you  suppress  it.  You  can  suppress  this  feature  by  putting  a 
comma  or  a  semicolon  after  the  last  variable.  A  comma  after  the  last  variable 
will  continue  the  display  at  the  next  11 -character  space  boundary.  To  illustrate 
this,  enter  and  run  the  following  program: 

10  PRINT  "0NE";1;  "TWO"; 2 
20  PRINT  "THREE"; 3 

Now  add  a  semicolon  to  the  end  of  the  statement  on  line  10  and  again  execute 
the  program  by  typing  RUN.  The  two  lines  of  display  will  now  occur  on  a 
single  line. 

You  have  been  displaying  the  numerals  by  inserting  them  directly  into 
the  PRINT  statement.  You  can,  if  you  wish,  display  the  contents  of  variables 
instead.  Try  entering  and  running  the  following  program,  which  uses  variable 
A%(I)  to  create  digits: 

10  FOR  1*1  TO  5 

20  AXa>»I 

30  NEXT 

40  PRINT  "ONE"  ;fl*<  1);  "TWO" J flK<2) ;  "THREE"  ;R*<3>; 

MF0UR";fl^:«:4) 

50  GOTO  50 

You  can  put  the  displayed  words  into  a  string  array  and  move  the  PRINT 
statement  into  the  FOR-NEXT  loop  by  changing  the  program  as  follows: 

10  DflTR  "ONE",  "TW0%  "THREE",  "FOUR 'V'FIVE" 
20  FOR  I»l  TO  5 
30  fl2(I>«I 
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40  READ  N*CI) 

50  PRINT.N*<I)JHX<I)i 

60  NEXT 

70  00T0  70 

This  version  of  the  program  is  not  well  written.  A%(I)  can  be  eliminated,  and 
N$  need  not  be  an  array  variable.  Can  you  rewrite  the  program  by  using  N$ 
and  removing  A%(I)  entirely? 

QUOTES  IN  STRINGS 

Although  most  BASIC  programs  will  not  need  to  print  quotation  marks, 
there  are  some  that  do,  such  as  "electronic  typewriters"  or  other  programs 
that  deal  with  words  rather  than  numbers. 

Since  quotation  marks  indicate  the  beginning  and  end  of  strings,  you 
cannot  put  them  in  the  middle  of  a  string.  You  can,  however,  put  a  quotation 
mark  into  a  string  or  a  PRINT  statement  by  using  the  BASIC  function 
CHR$.  CHR$  acts  like  an  array  of  all  possible  characters.  You  supply  a 
subscript,  and  CHR$  returns  the  character  corresponding  to  that  number. 
The  values  of  the  subscripts  and  the  characters  they  produce  are  listed  in 
Appendix  D.  The  value  for  a  quotation  mark  is  34.  Using  CHR$,  you  can 
print  a  quotation  mark  with  a  statement  such  as 

100  PRINTCHR*<34>;MTHIS  IS  DISPLACED  IN  QUOTES" J CHR*<34> 

If  you  PRINT  a  string  containing  control  characters,  such  as  CRSR  UP  or 
HOME,  you  must  take  an  additional  step.  Chapter  2,  as  you  may  recall, 
described  the  quote  mode.  In  quote  mode,  cursor  movement  keys  are  trans- 
lated into  special  characters  so  they  can  be  stored  in  strings.  This  allows  your 
program  to  perform  these  functions  while  it  is  running. 

Quote  mode  also  applies  to  output.  To  allow  you  to  LIST  programs 
containing  these  control  characters,  the  portion  of  BASIC  that  puts  informa- 
tion on  the  display  "watches"  for  quotes.  When  it  finds  a  quotation  mark,  it 
goes  into  quote  mode  and  displays  control  characters  in  the  reversed  form 
you  see  when  typing  them  into  a  program.  This  can  do  unpleasant  things  to  a 
carefully  planned  display. 

You  can  escape  from  quote  mode  while  printing  just  as  you  do  when 
typing  in  a  program:  by  using  a  second  quotation  mark  or  a  RETURN.  Since 
programs  that  print  quotation  marks  usually  print  them  in  pairs,  you  will 
seldom  see  a  problem.  If  your  program  must  print  only  one,  you  can  use 
CHR$  to  delete  the  first  one,  and  then  print  another  to  leave  quote  mode. 

100  PRINTCHR*<34);CHR*C20)jCHR*<34> j "SRVS  QUOTED  STRINGS"  j 
CHR*C34> 
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CHR$(20)  deletes  the  first  quotation  mark.  Only  the  second  one  will  appear 
on  the  screen. 

PRINT  FORMATTING  FUNCTIONS 

The  word  formatting  is  used  to  describe  the  process  of  arranging  infor- 
mation on  a  display  (or  a  printout)  to  make  it  easier  to  understand  or  more 
pleasing  to  the  eye.  If  you  had  only  the  PRINT  statement  to  work  with  and 
nothing  else,  formatting  could  become  a  complex  and  painful  chore.  For 
example,  suppose  you  want  to  display  a  heading  in  the  middle  of  the  top  line 
of  the  display.  Does  that  mean  displaying  space  codes  until  you  reach  the  first 
heading  character  position?  Not  only  would  that  be  time-consuming  and 
likely  to  cause  errors,  but  it  would  also  waste  a  lot  of  memory,  since  each  space 
code  must  be  converted  into  a  computer  instruction.  Fortunately,  C-128 
BASIC  provides  three  PRINT  formatting  aids:  the  SPC,  TAB,  and  POS 
functions. 

SPC  FUNCTION 

SPC  is  a  space-over  function.  You  include  SPC  as  one  of  the  terms  in  a 
PRINT  statement.  After  the  letters  SPC  you  include  in  parentheses  the 
number  of  character  positions  that  you  wish  to  space  over.  For  example,  you 
could  display  a  heading  beginning  at  the  leftmost  character  position  of  the 
display  as  follows: 

10  PR I NT "HERDING" 

To  center  the  heading  on  the  screen,  you  would  first  space  over  16 
character  positions,  as  follows: 

10  PRINT  SPCC16); "HERDING" 

Notice  the  semicolon  after  the  SPC  function.  A  comma  after  SPC  will  start 
displaying  text  at  the  next  11 -character  boundary,  following  the  number  of 
spaces  specified  by  SPC. 

When  you  include  the  SPC  function  in  a  PRINT  statement,  you  simply 
cause  the  next  printed  or  displayed  character  to  be  moved  over  by  the  number 
of  positions  specified  after  SPC;  no  other  PRINT  statement  syntax  is 
changed. 

TAB  FUNCTION 

TAB  is  a  tabbing  function  similar  to  typewriter  tabbing.  Suppose  you 
want  to  print  or  display  information  in  columns.  You  must  first  calculate  the 
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character  position  of  the  line  where  each  column  is  to  begin.  This  may  be 
illustrated  as  follows: 


Columns  begin  at  character  positions  0  and  13.  Now,  instead  of  computing 
space  codes  as  you  go  from  line  to  line,  following  each  column  entry  you 
simply  insert  a  TAB  function  in  the  PRINT  statement. 

Consider  one  line  of  the  display  example.  Counting  character  positions, 
you  could  display  the  line  without  tab  stops,  as  follows: 

10  PRINT  "JONES, P. J.  431-25-6277" 

Instead  of  inserting  space  codes,  you  could  use  the  space  function  and  shorten 
the  statement,  as  follows: 

10  PRINT  ,,J0NES,P.J.^SPC<3);,,431~25--6277', 

But  tabbing  is  easier  because  you  tab  to  a  known  column  number  instead  of 
counting  spaces. 

Note  that  the  entries  in  the  third  and  fourth  columns  are  numbers  that 
were  entered  as  text.  Try  rewriting  the  PRINT  statement  to  display  these  as 
numbers.  The  numbers  no  longer  align  as  they  did  when  they  were  displayed 
as  characters.  (Chapter  5  discusses  the  quirks  associated  with  display  format- 
ting.) In  this  case,  numbers  leave  a  space  for  a  negative  sign,  and  they  do  not 
display  zeros  occurring  after  the  decimal  point.  That  is  the  reason  there  are 
differences. 

POS  FUNCTION 

POS  returns  the  current  cursor  position.  The  position  is  returned  as  a 
number,  equal  to  the  column  number  where  the  cursor  is  blinking.  Write  the 
POS  function  as  POS(O). 

The  following  statement  demonstrates  the  capability  of  POS: 

10  PR I NT "CURSOR  POSITION  IS";POS<0j» 

Execute  this  statement  in  immediate  mode.  The  display  will  appear  as 
follows: 


Column  Number 


0 

JONES,  P.  J. 
BURKE,  P.  L. 
ROBINSON,  L.W 
etc. 


13 


431-25-6277 
447-71-7614 
231-80-8421 
etc. 


?" CURSOR  POSITION  IS";POS<0> 
CURSOR  POSITION  IS  18 
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The  cursor  was  at  character  position  18  after  CURSOR  POSITION  IS  was 
displayed.  If  you  add  some  spaces  after  IS  and  before  the  closing  quotes,  you 
will  change  the  number  18  to  a  larger  number. 

INPUT  STATEMENT 

When  an  INPUT  statement  is  executed,  the  computer  waits  for  input 
from  the  keyboard;  until  the  computer  receives  this  input,  nothing  else  will 
happen. 

An  INPUT  statement  begins  with  the  word  INPUT,  which  is  followed  by 
a  list  of  variable  names.  Entered  data  is  assigned  to  the  named  variables.  The 
variable  name  type  determines  the  form  in  which  data  must  be  entered.  A 
string  variable  name  (ending  with  a  $)  can  only  be  assigned  text  input;  any 
number  of  text  characters  can  be  entered  for  a  string  variable.  To  practice 
using  string  input,  key  in  the  following  short  program  and  run  it: 

10  INPUT  fi* 
20  PRINT  fl* 
30  GOTO  10 

Upon  executing  an  INPUT  statement,  the  computer  displays  a  question 
mark  and  then  waits  for  your  entry.  The  program  example  displays  any  text 
that  you  enter  as  you  enter  it.  The  text  is  also  displayed  a  second  time  because 
of  the  PRINT  statement  on  the  next  line.  The  first  display  occurs  when  the 
INPUT  statement  on  line  10  is  executed.  The  second  display  is  in  response  to 
the  PRINT  statement  on  line  20. 

You  input  integer  or  floating  point  numeric  data  by  listing  the  appropri- 
ate variable  names  following  INPUT.  Separate  individual  entries  with  com- 
mas. The  comma  is  not  used  for  punctuation  in  an  INPUT  statement.  The 
following  example  inputs  a  text  word,  an  integer  number,  and  a  floating  point 
number;  then  it  displays  these  three  entries.  Enter  and  run  the  program. 

10  INPUT  fl*,fl,flE 
20  PRINT  R*jAjRK 
30  GOTO  10 

You  must  enter  some  text  followed  by  a  comma,  then  an  integer  number 
followed  by  a  comma,  and  then  a  floating  point  number  followed  by  RETURN. 
Any  departure  from  this  input  sequence  will  cause  an  error;  following  an  error 
the  computer  displays  two  question  marks.  You  will  have  to  reenter  the  data  in 
the  correct  format.  If  the  computer  then  displays  a  question  mark  with  the 
message  REDO  FROM  START,  enter  the  data  again. 

Now  rewrite  the  PRINT  statement  so  that  AS,  A,  and  A%  are  in  an  order 
that  differs  from  that  in  the  INPUT  statement.  Rerun  the  program. 

As  discussed  earlier,  any  integer  can  be  represented  with  a  floating  point 
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number.  Therefore,  you  can  input  an  integer  value  for  a  floating  point 
variable.  You  cannot  input  a  floating  point  value  for  an  integer  variable, 
however.  You  cannot  enter  text  for  an  integer  or  a  floating  point  number,  but 
you  can  enter  a  number  for  a  text  variable:  the  number  will  be  interpreted  as 
characters  rather  than  a  numeric  value.  Try  these  variations  to  satisfy  yourself 
that  you  understand  the  data  entry  options. 

The  INPUT  statement  is  very  fussy;  its  syntax  is  too  demanding  for  any 
normal  human  operator.  Imagine  the  office  worker  who  knows  nothing  about 
programming.  On  encountering  the  types  of  error  messages  that  can  occur  if 
one  comma  is  out  of  place,  that  person  may  well  give  up  in  despair.  You  are 
therefore  likely  to  spend  a  lot  of  time  writing  "idiot-proof"  data  entry  pro- 
grams; these  are  programs  designed  to  watch  out  for  every  conceivable  type  of 
mistake  an  operator  can  make  when  entering  data.  An  idiot-proof  program 
will  cope  with  errors  in  a  way  that  the  operator  can  understand.  Chapter  4 
describes  data  entry  programming  in  detail. 

One  simple  way  to  avoid  data  entry  errors  is  to  use  the  INPUT  state- 
ment's ability  to  display  data.  You  can  precede  each  item  of  data  entry  with  a 
short  message  telling  the  operator  what  to  do.  The  message  appears  in  the 
INPUT  statement  as  text  between  quotes.  A  semicolon  must  occur  after  the 
text  to  be  displayed  and  before  the  first  input  variable  name.  Here  is  an 
example. 

10  INPUT  "ENTER  THE  NUMBER  1 " j  N 
20  IF  NOl  THEN  GOTO  50 
30  PRINT  "OK" 
40  GOTO  40 

50  PRINT  "NO,  DUMMVi " 
60  GOTO  10 

This  program  prints  a  message,  and  then  waits  for  a  single  data  entry. 

The  prompting  feature  of  INPUT  does  have  a  pitfall,  however:  if  the 
prompt  string  is  too  long,  BASIC  tries  to  read  the  prompt  along  with  the 
input  typed  at  the  keyboard.  This  will  happen  only  if  the  prompt  extends 
beyond  the  end  of  a  row  on  the  screen.  To  avoid  this  problem,  always  make 
sure  your  prompts  are  less  than  40  characters  long  in  C-64  mode  and  less  than 
80  characters  long  in  C-128  mode.  The  problem  can  also  arise  if  the  INPUT 
statement  follows  a  PRINT  statement  that  ends  with  a  semicolon.  Since  the 
prompt  starts  in  the  middle  of  the  line,  it  must  be  short  enough  to  ensure  that 
it  does  not  "overflow"  to  the  next  row  of  the  display. 

If  you  inadvertently  make  a  prompt  too  long,  you  may  find  yourself 
trapped.  BASIC  will  keep  telling  you  to  "REDO"  your  response  and  then 
display  the  prompt  again.  To  escape  from  this  trap,  use  the  DEL  key  to  delete 
the  prompt  and  then  type  your  response.  The  only  other  way  is  to  press  the 
RUN/ STOP  and  RESTORE  keys  simultaneously.  This  aborts  the  program. 
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"PRESETTING"  THE  RESPONSE  TO  INPUT 

After  printing  your  prompt,  INPUT  prints  a  question  mark  and  a  space. 
Anything  to  the  right  of  that  space  on  the  screen  is  treated  as  if  it  were  typed 
from  the  keyboard.  By  adding  backspaces  to  your  prompt,  you  can  "preset" 
the  response  so  that  the  user  need  only  press  RETURN.  To  use  this  feature,  add 
two  spaces  to  your  prompt  string,  followed  by  the  response.  Then  use  CRSR 
LEFT  to  move  the  cursor  back  to  the  first  of  the  added  spaces.  When  INPUT 
prints  its  question  mark  and  space,  they  will  replace  your  two  spaces,  posi- 
tioning the  cursor  on  the  response.  If  the  user  simply  presses  RETURN, 
INPUT  will  read  the  response  you  have  set  up  on  the  screen. 

You  can  also  preset  responses  by  assigning  in  advance  a  value  to  the 
variable  you  will  INPUT.  If  the  user  responds  with  just  a  RETURN,  the  value 
already  in  the  variable  is  not  changed.  Note,  however,  that  if  you  INPUT 
multiple  variables,  this  is  an  all-or-nothing  proposition:  if  the  value  for  the 
first  variable  is  typed  in,  values  for  all  variables  must  be  given. 

GET  STATEMENT 

The  GET  statement  inputs  a  single  character.  No  carriage  return  is 
needed .  The  single  character  input  can  be  any  character  the  C- 128  recognizes, 
or  it  can  be  a  numeric  value  between  0  and  9.  The  entry  will  be  interpreted  as  a 
character  if  a  string  variable  name  follows  GET.  Type  in  the  following  pro- 
gram and  run  it: 

10  GET  fit 
20  PRINT  R* 
30  GOTO  10 

When  you  run  this  program,  everything  will  race  off  the  top  of  the  display. 
Each  time  you  press  a  key,  the  character  typed  will  also  race  off  the  top  of  the 
screen.  This  happens  because  GET  does  not  wait  for  a  character  entry,  but 
assumes  the  entry  is  there.  You  can  make  GET  wait  for  a  specific  character  by 
testing  for  the  character  as  follows: 

10  GET  fl* 

20  IF  fl*0,,X"  THEN  GOTO  10 
30  PRINT  fi* 
40  GOTO  10 

This  program  waits  for  the  letter  X  to  be  entered.  Nothing  else  will  do. 

GET  can  also  be  programmed  to  wait  for  any  keyboard  entry.  This 
program  logic  makes  use  of  the  fact  that  the  GET  statement  string  variable  is 
assigned  a  null  character  code  until  a  character  is  input  at  the  keyboard.  The 
null  code,  00,  cannot  be  entered  from  the  keyboard,  but  can  be  specified 
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within  a  program  with  two  adjacent  quotation  marks  ("  ").  Here  is  the 
necessary  program  logic. 

10  GET  Fl* 

20  IF  fl$«"n  THEN  GOTO  10 
30  PRINT  fl* 
40  GOTO  10 

If  the  GET  statement  specifies  an  integer  or  floating  point  variable,  the 
input  is  interpreted  as  a  numeric  digit.  The  integer  or  floating  point  variable 
appearing  in  a  GET  statement  is  assigned  a  value  of  0  until  data  input  is 
received.  But  since  you  can  enter  0  at  the  keyboard,  program  logic  has  no  way 
of  knowing  whether  the  0  represents  a  valid  entry  or  the  absence  of  any  entry. 
This  can  present  problems  to  programming  logic  that  checks  for  an  entry,  as 
was  previously  shown.  For  this  reason,  GET  statements  usually  receive  string 
characters. 

Programs  use  the  GET  statement  most  frequently  when  generating 
dialog  with  an  operator.  For  example,  a  program  may  wait  for  an  operator  to 
indicate  that  he  or  she  is  there  by  entering  a  specific  character  (for  example, 
"Y"  for  "yes").  Here  is  the  appropriate  program  logic. 

10  PRINT  "OPERATOR !  RRE  VOU  THERE?  TVPE  V  FOR  "VES" 
20  GET  Pit 

30  IF  R$0"V"  THEN  GOTO  20 

40  PRINT  "OK,  LET'S  GET  ON  WITH  IT" 

Notice  that  this  sequence  never  displays  the  character  entered  at  the 
keyboard.  Try  rewriting  the  program  so  that  any  character  entered  in  the 
GET  statement  is  displayed. 

PEEK  and  POKE  Statements 

PEEK  and  POKE  are  two  C-128  BASIC  statements  that  you  will  encounter  in 
later  chapters.  The  C-128  computer  has  65,536  individual  memory  locations, 
each  of  which  can  store  a  number  ranging  between  0  and  255.  (This  strange 
upper  bound  is  in  fact  2s- 1.)  All  programs  and  data  are  converted  into 
sequences  of  numbers,  which  are  stored  in  this  fashion. 

The  PEEK  statement  lets  you  read  the  number  stored  in  any  C-128 
computer  memory  location.  Consider  the  following  PEEK  statement: 

10  flX=PEEK<200) 

This  statement  assigns  the  contents  of  memory  location  200  to  variable  A%. 
The  PEEK  argument  may  be  a  number,  as  shown,  an  integer  variable  name, 
or  an  integer  expression,  but  it  must  evaluate  to  the  address  of  a  memory 
location. 
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The  POKE  statement  writes  data  into  a  memory  location.  For  example, 
the  statement 

20  POKE  8000, flX 

stores  the  contents  of  variable  A%  in  memory  location  8000.  Each  POKE 
argument  may  be  a  number,  a  variable,  or  an  expression  with  a  value  between 
0  and  255.  A  floating  point  value  is  automatically  converted  to  an  integer. 

You  can  PEEK  into  read/ write  memory  or  read-only  memory,  but  you 
can  POKE  only  into  read /write  memory.  Read-only  memory,  as  its  name 
implies,  can  have  its  contents  read  but  cannot  be  written  into. 

END  and  STOP  Statements 

The  END  and  STOP  statements  halt  program  execution.  You  can  continue 
execution  by  typing  CONT.  You  don't  have  to  include  END  or  STOP  state- 
ments in  your  program,  but  these  statements  do  make  programs  easier  to  use. 

Many  of  the  programming  examples  given  in  this  chapter  have  used  a 
GOTO  statement  that  branches  to  itself  in  order  to  stop  program  execution. 
For  example,  the  statement 

50  GOTO  50 

will  execute  endlessly  since  the  GOTO  statement  selects  itself  for  the  execu- 
tion. You  could  replace  this  statement  with  a  STOP  statement.  When  a  STOP 
statement  is  executed,  a  message  of  this  format  will  appear: 

BREAK  IN  XXXX 

Then  execution  stops.  XXXX  is  the  line  number  of  the  STOP  statement.  If 
you  have  more  than  one  STOP  statement  in  your  program,  use  the  line 
number  to  identify  the  one  that  was  executed. 

Functions 

Another  element  of  C-128  BASIC  is  the  function,  which  in  some  ways  looks 
like  a  variable,  but  in  other  ways  acts  more  like  a  BASIC  statement. 

Perhaps  the  simplest  way  of  illustrating  a  function  is  to  look  at  an 
example  in  an  assignment  statement. 

10  fl»SQR(B> 

The  variable  A  has  been  set  equal  to  the  square  root  of  the  variable  B.  SQR 
specifies  the  square  root  function.  Here  is  a  string  function. 

20  C**LEFT*<D*,2) 
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In  this  example,  the  string  variable  C$  is  set  equal  to  the  first  two  characters  of 
string  variable  D$. 

Functions  can  substitute  for  variables  or  constants  anywhere  in  a  BASIC 
statement,  except  to  the  left  of  an  equal  sign.  In  other  words,  you  can  say  that 
A=SQR(B),  but  you  cannot  say  that  SQR(A)=B. 

You  have  already  used  four  functions.  SPC,  TAB,  and  POS  are  system 
functions  used  with  the  PRINT  statement  to  format  displays.  PEEK  is  also  a 
function. 

The  following  discussion  shows  you  how  to  use  functions.  This  is  neces- 
sarily a  brief  and  incomplete  summary  of  the  C-128  BASIC  functions,  but 
complete  descriptions  of  all  functions  are  given  in  Appendixes  E  and  F. 

You  specify  a  function  with  an  abbreviation  (such  as  SQR  for  square 
root),  followed  by  arguments  enclosed  in  parentheses.  In  the  case  of 
A=SQR(B),  SQR  requires  a  single  argument,  which  in  this  case  is  the 
variable  B.  For  C$=LEFT$(D$,2),  LEFTS  specifies  the  function;  the  two 
arguments  D$  and  2  are  enclosed  in  parentheses.  Generally  stated,  any 
function  will  have  one  of  the  following  two  formats: 


A  few  functions  need  three  arguments.  Each  function  argument  can  be  a 
constant,  a  variable,  or  an  expression. 

A  function  appearing  in  a  BASIC  statement  is  evaluated  before  any 
operators.  Every  function  in  a  BASIC  statement  is  reduced  to  a  single 
numeric  or  string  value  before  any  other  part  of  the  BASIC  statement  is 
evaluated.  For  example,  the  SQR  and  SIN  functions  are  evaluated  first  in  the 
following  statement: 

10  B«24.7*<SQR<C)+3>-SIN<0.2+D) 

Suppose  SQR(C)=  6.72  and  SIN(0.2+  D)=  0.625.  The  statement  on  line 
10  will  first  be  reduced  to 

10  B*24.7*<6.72+5> -0.625 


Single  argument  for  a  function 
that  has  just  one  argument 


function  (argl) 
function  (argl,  arg2) 


Two  arguments  for  a  function 
that  needs  two  arguments 

Letters  that  specify  the  function 


This  simpler  statement  is  then  evaluated. 
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ARITHMETIC  FUNCTIONS 

Here  is  a  list  of  the  arithmetic  functions  that  can  be  used  with  C-128 
BASIC. 

INT         converts  a  floating  point  argument  to  its  integer  equivalent 
by  truncation. 

SGN        returns  the  sign  of  an  argument:  +1  for  a  positive  argu- 
ment, —  1  for  a  negative  argument,  0  for  0  argument. 

ABS        returns  the  absolute  value  of  an  argument.  A  positive 

argument  does  not  change;  a  negative  argument  is  con- 
verted to  its  positive  equivalent. 

SQR        computes  the  square  root  of  the  argument. 

EXP        raises  the  natural  logarithm  base  e  to  the  power  of  the 
argument  (earg). 

LOG       returns  the  natural  logarithm  of  the  argument. 

RND       generates  a  random  number.  There  are  some  rules  regard- 
ing use  of  RND;  they  are  described  in  Chapter  5. 

SIN         returns  the  trigonometric  sine  of  the  argument,  which  is 
treated  as  a  radian  quantity. 

COS        returns  the  trigonometric  cosine  of  the  argument,  which  is 
treated  as  a  radian  quantity. 

TAN        returns  the  trigonometric  tangent  of  the  argument,  which 
is  treated  as  a  radian  quantity. 

ATN        returns  the  trigonometric  arctangent  of  the  argument, 
which  is  treated  as  a  radian  quantity. 

The  following  example  uses  an  arithmetic  function: 

10  fi=2„743 
20  B«INT<fl>+7 
30  PRINT  E 
40  STOP 

When  you  execute  this  program,  the  result  displayed  is  9,  since  the  integer 
value  of  A  is  2.  As  an  exercise,  change  the  statement  on  line  10  to  an  INPUT 
statement.  Change  line  40  to  GOTO  10.  Now  you  can  enter  a  variety  of  values 
for  A  and  watch  the  integer  function  at  work.  Use  this  program  to  experiment 
with  various  functions. 

Here  is  a  more  complex  example  using  arithmetic  functions. 
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10  INPUT  fl.B 

20  IF  LOG<flX0  THEN  fl-l/fl 
30  PRINT  SQR<fl>*EXP(B) 
40  GOTO  10 


If  you  understand  logarithms,  then  as  an  exercise  change  the  statement  on 
line  20,  replacing  the  LOG  function  with  arithmetic  functions  that  perform 
the  same  operation. 

The  argument  of  a  function  can  be  an  expression;  the  expression  itself 
may  contain  functions.  For  example,  change  line  30  to  the  following  state- 
ment and  rerun  the  program: 

30  PRINT  SQR<fl*EXP<B>+3, 

Now  experiment  with  arithmetic  functions  by  creating  PRINT  statements 
that  make  complex  use  of  arithmetic  functions. 

STRING  FUNCTIONS 

String  functions  allow  you  to  manipulate  string  data  in  a  variety  of  ways. 
You  may  never  need  to  use  some  of  the  arithmetic  functions,  but  you  must 
make  the  effort  to  learn  every  string  function. 

Here  is  a  list  of  the  string  functions  that  can  be  used  with  C-128  BASIC. 

STR$       converts  a  number  to  its  equivalent  string  of  text 
characters. 

VAL        converts  a  string  of  text  characters  to  their  equivalent 
number  (if  such  a  conversion  is  possible). 

CHR$      converts  an  8-bit  binary  code  to  its  equivalent  ASCII 
character. 

ASC        converts  an  ASCII  character  to  its  8-bit  binary  equivalent. 

LEN        returns  the  number  of  characters  contained  in  a  text  string. 

LEFTS     extracts  the  left  part  of  a  text  string.  Function  arguments 
identify  the  string  and  its  left  part. 

RIGHTS  extracts  the  right  part  of  a  text  string.  Function  arguments 
identify  the  string  and  its  right  part. 

MIDS      extracts  the  middle  section  of  a  text  string.  Function 

arguments  identify  the  string  and  the  required  mid  part. 

String  functions  let  you  determine  the  length  of  a  string,  extract  portions 
of  a  string,  and  convert  between  numeric,  ASCII,  and  string  characters. 
These  functions  take  one,  two,  or  three  arguments.  Here  are  some  examples. 
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STR*<14) 
LEN( "RBC" ) 
LEN<fl$+B:$) 
LEFTIST*,  1) 

SYSTEM  FUNCTIONS 

In  the  interest  of  completeness,  C-128  BASIC  system  functions  are  listed 
in  this  section.  They  perform  operations  that  you  are  unlikely  to  need  until 
you  are  an  experienced  programmer.  The  only  system  function  you  are  likely 
to  use  fairly  soon  is  the  time-of-day  function.  If  you  print  many  variations  of  a 
report  (or  any  other  material)  in  a  single  day,  you  may  wish  to  print  the  time  of 
day  at  the  top  of  the  report.  This  will  tell  you  the  sequence  in  which  these 
reports  were  generated. 

PEEK     fetches  the  contents  of  a  memory  byte. 

TI$,TI     fetches  system  time,  as  maintained  by  a  program  clock. 

FRE       returns  available  free  space — the  number  of  unused 
read/ write  memory  bytes. 

SYS        transfers  to  subsystem. 

USR       transfers  to  user  assembly  language  program. 

USER-DEFINED  FUNCTIONS 

In  addition  to  the  many  functions  that  are  a  standard  part  of  C-128 
BASIC,  you  can  define  your  own  arithmetic  functions,  providing  they  are  not 
very  complicated.  User-defined  string  functions  are  not  allowed.  Here  is  an 
example  of  a  short  program  that  uses  a  DEF  FN  (define  function)  statement. 

10  DEFNP<X)«100*X 
20  INPUT  fl 
30  PRINT  fliFNP(fl) 
40  GOTO  20 

Following  the  DEF  FN  entry,  you  can  have  any  valid  floating  point 
variable  name.  In  this  case,  P  was  entered;  therefore  the  function  name 
becomes  FNP.  If  the  variable  name  were  AB,  the  function  name  would  be 
FNAB. 

In  the  DEF  FN  statement,  a  single  variable  enclosed  in  brackets  must 
follow  FN.  This  is  the  only  variable  name  that  can  appear  to  the  right  of  the 
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equal  sign.  This  variable  name  is  used  within  the  DEF  FN  statement  only;  you 
can  use  it  in  the  body  of  the  program  without  affecting  the  function. 


CHAPTER 


Advanced  BASIC  ^fl 
Programming  ™fr 


Although  the  previous  chapter  covered  most  of  the  inner  workings  of  C-128 
BASIC,  you  will  find  that  there  is  much  more  to  be  learned  about  program- 
ming. Whereas  Chapter  3  covered  the  language  itself,  this  chapter  and  those 
that  follow  provide  programming  techniques  and  hints  that  will  help  you  get 
the  most  out  of  your  C-128. 

Because  this  chapter  covers  advanced  programming,  program  examples 
and  explanations  will  be  longer.  You  will  probably  want  to  enter  and  run  each 
example  in  order  to  understand  more  clearly  the  concepts  being  discussed. 

Many  of  the  program  examples  included  in  this  chapter  are  designed  for 
use  in  programs  you  write  yourself.  Some  are  written  as  subroutines,  and 
others  can  be  turned  into  subroutines  with  minor  changes. 
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ADVANCED  EDITING  FUNCTIONS 

Up  to  this  point,  all  of  the  operations  discussed  were  basically  the  same  for 
both  the  C-64  mode  and  C-128  mode  of  the  C-128.  Beginning  with  this 
chapter,  some  of  the  operations  will  be  identified  with  the  appropriate  mode 
as  necessary. 

One  of  the  first  differences  this  chapter  covers  is  the  advanced  line 
editing  features  available  in  C-128  mode.  The  special  functions  are  AUTO, 
DELETE,  and  RENUMBER. 

AUTO 

The  AUTO  function  will  automatically  number  program  lines  for  you.  The 
default  increment  value  is  10;  so  if  you  begin  a  program  at  line  10,  for  example, 
each  line  will  be  an  increment  of  10  and  will  be  numbered  10, 20, 30, 40,  and  so 
on. 

The  basic  form  of  the  AUTO  command  is 

AUTO  pi 

where  pi  is  the  increment  value  between  line  numbers.  To  begin  auto  line- 
numbering,  type  AUTO  and  the  increment  number.  The  C-128  will  respond 
with  READY.  Then  enter  the  first  line  number  and  begin  programming.  Auto 
line-numbering  will  begin  with  the  next  line  of  your  program. 

To  end  auto  line-numbering,  enter  the  command  AUTO  with  no  line 
number. 

DELETE 

The  DELETE  command  removes  lines  from  your  program.  DELETE  can 
have  up  to  two  parameters.  The  basic  form  of  DELETE  is 

DELETE  pl9p2 

where  pi  is  the  number  of  the  first  line  to  delete  and  p2  is  the  last  line  to  delete. 
If  you  wanted  to  delete  lines  40  through  80  of  your  program,  the  command 
would  be 

DELETE  40-80 

To  delete  all  of  the  program  from  line  80  on,  the  command  would  be 

DELETE  80- 
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The  command  to  delete  everything  up  to  line  40  would  be 

DELETE  -40 

RENUMBER 

The  RENUMBER  command  renumbers  the  lines  of  your  program.  It  can 
have  up  to  three  parameters.  The  basic  form  of  the  RENUMBER  command 
is 

RENUMBER  pl9p29p3 

where  pi  is  the  new  beginning  line  number  you  want,/?2  is  the  line  increment 
you  want,  and p3  is  the  line  number  you  want  to  begin  renumbering  from.  For 
example, 

RENUMBER 

defaults  to  a  starting  line  number  of  10  and  increments  the  lines  by  10. 
However, 

RENUMBER  200,    10,  120 

will  begin  renumbering  at  line  120,  changing  that  line  to  200  and  incrementing 
by  tens  from  there;  for  example,  210,  220,  230 ....  If  you  leave  a  parameter 
out,  the  C-128  will  assume  that  you  want  the  default  value.  For  example, 

RENUMBER  20, , lO 

will  begin  renumbering  at  line  10,  change  that  line  to  20,  and  increment  by 
tens  from  there. 


PROGRAMMING  WITH  STRINGS 

A  string  can  do  much  more  than  simply  contain  data  that  cannot  be  expressed 
in  numeric  form.  String  operations  and  functions  give  you  the  ability  to 
change  and  manipulate  data. 

Concatenating  Strings 

Strings  can  contain  alphabetic  characters,  numeric  characters,  or  combina- 
tions of  these.  When  handling  strings,  you  will  find  it  useful  to  link  shorter 
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strings  end-to-end  in  chainlike  fashion  to  create  one  large  string.  This  linking 
process,  as  you  may  recall,  is  called  concatenation. 


String  1 


String  2 


String  3 


String  4 


String  1       i       String  2      j       String  3 


Suppose,  for  example,  you  want  to  create  one  large  string,  Z$,  containing 
the  alphabet  A  through  Z.  To  do  this,  you  can  link  the  last  character  of  A$  to 
the  first  character  of  J$,  and  the  last  character  of  J$  to  the  first  character  of 
S$,  as  shown  here. 


A$ 


J$ 


S$ 


A 

B 

c 

D 

E 

F 

G 

H 

I 

J 

K 

L 

M 

N 

O 

P 

0 

R 

S 

T 

U 

V 

w 

X 

Y 

Z 

A 

B 

c 

D 

F 

G 

H|. 

J 

K 

L 

M 

N 

p 

Q 

R 

S 

T 

u 

V 

w 

X 

Y 

A 

When  a  plus  sign  appears  between  two  numeric  expressions,  it  adds  the 
values  of  the  expressions.  However,  when  a  plus  sign  appears  on  either  side  of 
string  variables,  it  will  concatenate  the  strings. 

The  same  is  not  true  of  the  minus  sign.  Strings  cannot  be  separated  or 
"de-concatenated"  in  the  same  way  they  are  concatenated;  they  cannot  be 
"subtracted"  the  way  they  are  "added."  For  instanc,  to  create  string  X$ 
containing  the  contents  of  J$  and  S$  from  the  original  strings  A$,  J$,  S$,  and 
Z$,  it  would  be  incorrect  to  type 


Try  it  yourself:  enter  the  values  of  A$,J$,S$,  and  type  X$  = 
Z$— A$  into  the  C-128  as  shown.  The  computer  will  respond  with  the  message 
?TYPE  MISMATCH  ERROR  IN  LINE  50,  as  shown: 
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10  H$="RBCDEFGHI " 
20  JS^'JKLMNOPQR'' 
30  Si^'STUVUXYZ" 
40  Z*=fi$+J$+S:* 

50  X$=Z$-f\$   Incorrect  attempt  to  get  J  through  Z  string 

60  PRINT  fit 

RUN 

?TVPE  MISMATCH 
ERROR  IN  50 


The  correct  way  to  extract  part  of  a  large  string  is  to  use  string  functions. 
With  the  LEFTS,  MID$,  and  RIGHTS  functions  it  is  possible  to  extract  any 
portion  of  a  string.  In  the  current  example,  the  letters  J  through  Z  can  be 
extracted  as  follows: 


50  X*=RIGHT$CZ$, 17) 


x$= 


A 

B 

C 

D 

E 

F    G  |  H  |  I  |  J  |  K  |  L 

M 

N 

0    P   Q  |  R  |  S    I  |  r  |  V   W  \    Y  z 

X$ 

J  1 

K  1 

I.  1 

M  |  N  |  O  |  P  |  Q  |  R  |  S  | 

I 

I 

\    \\    \  |  Y  |  Z 

The  number  17  points  to  the  seventeenth  character  from  the  right 
(RIGHTS)  as  the  first  character  of  the  string  and  includes  the  rest  of  the 
characters  to  its  right.  The  string  may  also  be  built  by  concatenating  J$  and 
S$,  as  shown  here. 


50  X*=J*+S* 


x$  = 

J 

K 

L 

M 

N 

o 

P 

0 

R 

+ 

s 

T 

U 

V 

W 

X 

Y 

Z 

x$  = 

J 

K 

L 

M 

P 

Q 

R 

S 

T 

U 

V 

W 

Y 

Z 

Numeric  Strings 

A  numeric  string  is  a  string  whose  contents  can  be  evaluated  as  a  number. 
Numeric  strings  can  be  created  in  two  different  ways,  each  yielding  slightly 
different  results. 
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When  numeric  variables  are  assigned  to  numeric  strings  with  the  STR$ 
function,  the  sign  value  preceding  the  number  (blank  if  positive,  —  if  negative) 
is  transferred  along  with  the  number.  This  is  shown  in  the  following  short 


18  RB*1234S 

20  Pim  -1*3.14159265 
38  T$»STRi<fiB> 
40  N**STRfCPn 
50  PRINT  ,,fiB«,,ifil 
60  PRINT  "Tf^'iTi 
70  PRINT  nti$*»iH* 


%\Jft  r  Space  left  for  sign  value 

RB~  12345 
T$=  12345 
N*«-3. 14159265 


However,  if  a  number  enclosed  in  quotation  marks  is  entered,  or  if  the  number 
is  entered  as  a  string  with  an  INPUT  or  READ  statement,  then  the  numeric 
string  is  treated  like  any  other  alphabetic  or  graphic  string.  No  blank  for  a 
positive  sign  value  is  inserted  before  the  number.  This  is  demonstrated  in  the 
following  program: 


10  RB* 12345 

20  T**" 12345" 

30  REfiD  R* 

40  DATA  12345 

50  PRINT  "RB*" JflB 

60  PRINT  "T^'ST* 

70  PRINT  "Rt^'iR* 


For  example,  suppose  that  you  wanted  to  concatenate  the  two  numeric 
strings  T$  and  Q$  to  make  a  new  numeric  string  W$  so  that  the  string  W$ 
contained  the  ten  digits  1,  2,  3,  4,  5,  6,  7,  8,  9,  0.  Here  is  one  possible  way. 


program: 


RUN 


RB=  12345 
T*= 12345 
R*= 12345 


Space  inserted 
No  space  inserted 
No  space  inserted 
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40  Q**STR*<Q> 

50  WS«T$+Qt   Create  new  string 

60  PRINT  UW$= 

RUN 

Wt=  12345  67890 


Why  are  there  blanks  before  the  1  and  6?  The  T$  and  Q$  strings  were 
originally  positive  numeric  variables  T  and  Q.  When  T  and  Q  were  converted 
from  numbers  into  strings,  the  blank  sign  positions  were  transferred  along 
with  the  numbers. 


) 

(>    1    2   3  4  5 

Q 

^  6   7   8   9  0 

£   1    2   3  4  5 

Q$ 

^  6   7   8   9  0 

represents  a  space  code 


Therefore,  when  T$  and  Q$  are  concatenated,  the  new  string  W$  contains  a 
first-digit  blank  and  an  embedded  blank  before  the  first  digit  of  Q$. 

T$         +         Q$  W$ 

'  h  1  1  |  2  |  3  |  4  1  5  |     |  h  |  ft  |  7  |  K  |  9  |  0  |     |  h  |  1  [  2  |  3  |  4  |  5  [  h  |  6  |  7  |  X  |  9~fo] 

£  represents  a  space  code 

To  get  rid  of  the  blanks,  go  back  to  the  separate  strings  T$  and  Q$.  Look 
again  at  the  contents  of  T$  and  Q$.  The  only  values  you  want  in  W$  are  the 
numbers  to  the  right  of  the  sign  value  in  both  T$  and  Q$.  With  the  LEFTS, 
MID$,  and  RIGHTS  commands  you  can  select  any  character  or  group  of 
characters  from  within  a  given  string.  You  want  all  the  characters  to  the  right 
of  the  first  character,  which  is  the  sign  value  (either  blank  or  — ).  T$  = 
MID$(T$,2)  does  the  trick. 


Before:  After: 


p 

1 

2 

3 

4 

5 

T$ 

1 

2 

3 

4 

5 
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Since  the  first  digit  needed  is  in  the  second  position  of  the  string,  the 
C-128  is  instructed  to  use  only  the  values  starting  in  the  second  position.  You 
can  concatenate  T$  and  Q$  and  drop  the  leading  blanks  all  in  one  statement. 


W$=  MID$(T$,2)+MID$(Q$,2) 


Accept  T$,  starting 
with  second  character 


Accept  Q$,  starting 
with  second  character 


Concatenate 
T$  and  Q$ 


The  example  program,  amended  to  eliminate  the  sign  digits,  appears  as 
follows: 


10  T* 12345 

T 


1)12345 


20  Q«67890 

Q  = 


f)67890 


30  T$«STR*<T) 

T$ 


40  Q**STR*<Q> 


Q$  = 

*> 

6 

7 

8 

9 

0 

M*ttIM<:Tt,  2>+MID*<Q*>  2> 

W$  =  T$ 

1 

2  3 

4 

5 

+  Q$ 

6 

7 

8    9  0 

W$  = 

1 

2 

3 

4 

5 

6 

7  8 

9 

0 

60  PRINT  "U**";*** 


RUN 

U$= 1234567890 


ADVANCED  BASIC  PROGRAMMING  121 


INPUT  AND  OUTPUT  PROGRAMMING 


It  is  usually  easy  for  beginning  programmers  to  become  acquainted  with  the 
way  BASIC  calculates  numbers.  When  you  write  programs  that  receive  input 
from  the  keyboard  and  display  data  on  the  screen,  however,  the  programming 
becomes  trickier. 

Nearly  every  program  requires  some  kind  of  input  from  the  keyboard.  If 
you  are  the  person  operating  the  computer,  you  can  probably  put  together 
some  INPUT  statements  that  get  the  required  data  and  process  it  in  your 
program.  But  if  someone  else  is  operating  the  computer,  sooner  or  later  the 
wrong  key  will  be  pressed  or  an  incorrect  entry  will  be  made.  Every  computer 
operator  will  make  mistakes  at  some  time.  You  should  write  programs  that 
allow  for  conceivable  human  errors. 

The  same  is  true  for  output  programming.  If  you  display  the  results  of  a 
program  with  a  set  of  PRINT  statements,  those  results  have  to  be  readable  to 
the  person  looking  at  the  display.  This  does  not  happen  by  hacking  away  at 
program  statements  until  the  output  looks  a  little  better;  you  must  give  it 
some  thought  while  you  are  writing  the  program. 

Assume  that  you  want  to  write  a  program  that  inputs  names  and 
addresses.  You  could  write  a  program  to  do  this  quickly  and  easily. 

10  REM  NAME/ ADDRESS  PROGRAM 

20  DIM  NM*<20),flD*C20)iCS*<20>,ZC*<20> 

21  REM  ARRAVS  RRE : 

22  REM  NM#<>  FOR  NAME 

23  REM  AD*0  FOR  ADDRESS 

24  REM  CSSO  FOR  CI  TV  AND  STATE 
26  REM  ZC*0  FOR  ZIP/POSTAL  CODE 
30  FOR  1=1  TO  20 

40  INPUT  "NAME • " j  NMf ( I > 

50  INPUT  "ADDRESS : " J AD$(  I > 

60  INPUT  "CITY,   STATE: »;CS$<I) 

70  INPUT  "ZIP/POSTAL  CODE : " j ZC*< I > 

80  NEXT  I 

90  END 


Here  is  an  example  of  how  the  program  would  appear  on  the  display. 
RUN 

NAME:?  NAM  THANG 

ADDRESS : ?  2000  CONSTITUTION  DR. 

CI TV,  STATE:?  CASTRO  VALLEY,  CA. 

?EXTRA  IGNORED 

ZIP/POSTAL  CODE:?  91912 

NAME:?  PETER  BILT 
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ADDRESS:?  200  KNOW  PL. 

CI TV,  STATE:?  AMARILLO,  TEXAS 

?EXTRA  IGNORED 

ZIP/POSTAL  CODE:?  65432 

In  this  program  the  C-128's  screen  is  unformatted.  The  screen  width  is  40 
characters  in  C-64  mode,  and  80  characters  in  C-128  mode;  some  of  the 
entered  names  and  addresses  wrap  around  to  the  line  below  the  original  entry 
because  the  entry  message,  or  prompt,  takes  up  several  spaces  on  the  input 
line. 

While  running  this  program,  the  person  entering  names  and  addresses 
might  discover  a  mistake  in  a  name  after  pressing  RETURN.  But  the  operator 
can't  go  back  to  fix  the  name  when  the  program  is  asking  for  address  input. 

Other  problems  with  this  program  are  obvious  if  you  enter  and  run  it. 
The  display  is  not  very  easy  to  read.  One  entry  for  a  name  and  address  follows 
another,  all  the  way  down  the  screen.  This  kind  of  clutter  will  increase  the 
probability  of  incorrect  entries. 

The  INPUT  statement  on  line  60  will  cause  the  program  to  fail  if  the 
operator  puts  a  comma  between  the  city  and  state  when  entering  them.  The 
city  and  state  have  to  be  entered  without  a  comma  between  them.  Try  entering 
a  city  and  state  separated  by  a  comma  (for  example,  OAKLAND,  CALI- 
FORNIA). This  is  what  you'll  get: 

ADDRESS : ?  OAKLAND,  CALIFORNIA 
?EXTRA  IGNORED 

Recall  from  Chapter  3  that  the  INPUT  statement  allows  you  to  enter 
more  than  one  item  of  data  on  a  single  line,  as  long  as  each  one  is  separated  by 
a  comma.  Therefore,  when  OAKLAND,  CALIFORNIA  was  entered,  C-128 
BASIC  interpreted  it  as  two  separate  strings  when  only  one  string  was 
expected  —  hence  the  7EXTRA  IGNORED  message.  In  addition  to  the  error 
message,  the  program  stored  only  OAKLAND  and  discarded  CALIFOR- 
NIA, which  was  considered  "extra"  input. 

Screen  Layout 

With  the  display  starting  at  row  0,  column  0  (the  upper-left  corner),  the 
rightmost  column  is  39  in  C-64  mode  and  79  in  C-128  80-column  mode,  and 
the  lowest  row  is  24  in  both  modes.  The  screen  layout  in  this  grid  form  is  a  set 
of  coordinates.  A  set  of  coordinates  is  the  point  at  which  a  particular  column 
and  row  intersect  on  the  display. 
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Column 

!  2  3  4  5  6  7  8  9  10  1 1  12  1314151617  181920212223  24  252627  2829303 1  32333435363738  39 


9 
10 
1 1 
12 
13 
14 
15 
16 
17 
18 
19 
20 
21 
22 
23 
24 


A  set  of  coordinates  on  the  C-128  screen  is  expressed  as  {row,column)\ 
that  is,  the  coordinates  of  the  twelfth  row  and  twentieth  column  will  be 
expressed  as  (11,19).  The  first  column  of  the  fourth  row  is  (3,0),  and  so  on. 
(Remember  that  the  row  and  column  numbers  start  at  0,  not  1.) 

The  coordinates  (11,19)  would  appear  at  this  point  on  the  screen  in 
40-column  mode. 

Column 

12  3  4  5  6  7  8  9  101 1 12  13  14  151617181920212223  2425262728  29303132333435363738  39 


I 

2 
3 
4 
5 
6 
7 
8 
9 
10 


14 
15 
16 
17 
18 
19 
20 
21 
22 
23 
24 
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Creating  a  Formatted  Display 

Keep  in  mind  the  maximum* possible  length  of  each  entry.  For  instance,  a 
name  with  a  job  title,  such  as  MAJOR  SEIDELL  —  DIRECTOR  OF  STRA- 
TEGIC OPERATIONS,  will  wrap  around  to  the  next  display  line  if  you  are  in 
40-column  mode.  Allow  space  for  such  entries  when  you  format  a  display. 
Centering  prompts  on  the  display  will  also  make  it  appear  more  orderly. 

Formatted  displays  should  be  used  in  programs  that  require  a  good  deal 
of  data  entry.  Three  distinguishing  features  of  proper  data  entry  techniques 
are  a  readable,  uncluttered  display;  clear  directions  to  the  operator;  and  the 
ability  of  the  operator  to  correct  mistakes. 

Programming  Cursor  Movement 

If  you  encountered  the  C-128's  quote  mode  while  entering  program  state- 
ments, you  will  already  know  how  to  program  cursor  movement. 

If  you  edit  a  program  statement  containing  a  string  constant,  C-128 
BASIC  will  interpret  a  control  key  as  an  actual  character  within  the  string  you 
are  trying  to  edit.  For  example,  when  you  press  the  CRSR  UP/ DOWN  key 
between  the  quotes  in  a  string,  it  will  appear  as  an  inverse-video  Q  on  the 
screen.  Instead  of  moving  the  cursor  up  or  down  one  line  as  you  intended, 
C-128  BASIC  inserted  the  CRSR  UP/  DOWN  key  into  the  string.  If  you  print  the 
string  containing  the  cursor  control  character,  the  cursor  will  move  down. 

The  statement 

1010  r»»  "  immmmmmamu 

set  up  a  string  of  22  CRSR  DOWN  characters  that,  when  printed  by  a  PRINT 
statement,  will  move  the  cursor  down  22  rows.  Likewise,  a  string  containing 
21  CRSR/ RIGHT  characters  will  move  the  cursor  to  the  right  21  spaces. 

1020  C*c:  ftiiftftiiiftiftiMiii 

These  strings  containing  the  cursor  control  characters  will  allow  you  to 
display  a  character  anywhere  on  the  display  screen. 

A  CURSOR  MOVEMENT  SUBROUTINE 

With  three  strings  containing  the  cursor  control  characters  to  move  to 
the  home  position,  down,  and  to  the  right,  it  is  possible  to  move  to  any 
coordinate  position  on  the  C-128  display.  How? 

The  coordinates  of  the  upper-left  corner  of  the  screen  are  (0,0).  You  can 
move  the  cursor  anywhere  by  printing  a  string  containing  the  CLR  HOME  key, 
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followed  by  strings  that  move  the  cursor  down  and  to  the  right.  Here  is  an 
example. 

10  REM  PROGRAMMED  CURSOR  MOVEMENT 
20  PRINT        :REM  CLEAR  THE  SCREEN 
30  Rtf*20  :  C5i=4  :  GOSUB  1000 
40  PRINT  " IGNORANCE  IS  BLISS" 
50  GOTO  50 

1000  REM  CURSOR  POSITIONING  SUBROUTINE 

1010  k$^rmmmmmMm»immm»v> 
l 020  c** " iiiiiiiiiiiiiiiiiiiiiii" 

1030  PRINT  "M";    : REM  MOVE  CURSOR  TO  <0,0) 
1040  PRINT  LEFT* < R*,  RH >;  LEFT* CC^CH); 
1050  RETURN 

Line  20  clears  the  screen,  removing  any  old  text  from  the  display.  (This 
has  nothing  to  do  with  cursor  positioning;  it  is  just  "housekeeping"  to  make  a 
cleaner  display.)  The  integer  variables  R%  and  C%  on  line  30  stand  for  "row" 
and  "column. "The  three  statements  combined  on  line  30  set  the  row  (20)  and 
column  (4),  followed  by  a  GOSUB  that  moves  the  cursor  to  the  coordinates 
(20,4). 

You  may  not  understand  why  the  cursor  must  go  to  (0,0)  first.  In  order 
for  the  program  to  move  the  cursor  to  the  correct  coordinates,  it  has  to  know 
how  many  rows  and  columns  the  cursor  is  from  the  coordinates  you  selected. 
The  easiest  and  most  efficient  way  to  do  this  is  to  move  to  (0,0)  first,  because 
the  program  will  always  know  exactly  how  many  times  the  cursor  must  move 
in  order  to  reach  the  coordinates  —  in  this  case,  20  rows  down  and  4  columns 
right. 

Look  at  the  cursor  movement  subroutine  line  by  line,  starting  with  lines 
1010  and  1020.  These  two  lines  are  assignment  statements  that  set  up  (initial- 
ize) the  cursor  movement  strings.  R$  contains  22  CRSR  DOWN  control  charac- 
ters; C$  contains  21  CRSR  RIGHT  characters. 

Line  1030  prints  the  CLR  HOME  character,  thus  positioning  the  cursor  at 
(0,0).  Line  1040  does  the  real  work:  it  uses  the  LEFTS  string  function  to  print 
the  first  20  characters  in  R$  and  then  the  first  10  characters  in  C$. 

This  cursor  movement  subroutine  will  be  an  integral  part  of  creating  and 
using  formatted  displays. 

The  CHR$  Function: 
Programming  Characters 
In  ASCII 

If  you  cannot  press  a  key  to  include  a  character  within  a  text  string,  you  can 
still  select  the  character  by  using  its  ASCII  value. 

The  CHRS  function  translates  an  ASCII  code  number  into  its  character 
equivalent.  This  is  the  format  of  the  CHR$  function. 
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PRINT  CHR$(xxx) 

 ASCII  number  from  0  to  255  of 

desired  character  or  control 

To  obtain  the  ASCII  code  for  a  character,  refer  to  Appendix  B:  scan  the 
columns  until  you  find  the  desired  character  or  cursor  control  and  then  note 
the  corresponding  ASCII  code  number.  Insert  this  number  between  the  two 
parentheses  of  the  CHR$  function.  For  example,  to  create  the  symbol  $  from 
its  ASCII  code,  look  up  the  ASCII  code  for  $  in  Appendix  A.  You  will  notice 
that  $  has  two  ASCII  values:  36  and  100.  Which  value  should  you  use?  Either 
number  works.  But  for  good  programming  technique,  once  you  select  one 
number  over  the  other,  use  that  number  consistently  throughout  the  program. 
Insert  36  into  the  CHR$  function  as  follows: 

PRINT  CHR$(36> 

Try  displaying  this  character  ($)  in  immediate  mode: 
PRINT  CHRS<36> 

Now  try  displaying  ASCII  code  100. 

PRINT  CHR*<100) 
t 

The  result  is  the  same.  Experiment  in  immediate  mode  using  any  ASCII  code 
from  0  to  255. 

You  can  use  the  CHR$  function  in  a  PRINT  statement  as  follows: 

10  PRINT  CHR»<36);CHR*<42>jCHR*<166> 

RUN 

$m 

The  CHR$  function  lets  you  include  otherwise  unavailable  characters  such  as 
RETURN,  INS/ DEL,  and  the  quote  character  (")  in  a  PRINT  statement's 
parameters. 

You  can  also  use  the  CHR$  function  to  check  for  special  characters  such 
as  RETURN  and  INS/ DEL.  Suppose  a  program  must  check  character  input  at 
the  keyboard,  looking  for  a  RETURN  key.  You  could  check  for  a  RETURN 
(which  has  an  ASCII  code  of  13)  as  follows: 

10  GET  X$:IF  X*OCHR«<13>  THEN  10 
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This  test  would  be  impossible  if  you  tried  to  put  RETURN  between  quotation 
marks. 

20  IF  XtO,,[TETpN□,,  THEN  10 

Impossible 

This  does  not  work,  because  pressing  the  RETURN  key  following  the  first  set  of 
quotation  marks  automatically  moves  the  cursor  to  the  next  line. 

20  IF  X$On   Press  return  key 


If  you  attempt  to  program  the  INS/ DEL  or  the  RETURN  key,  you  will 
encounter  some  surprising  results. 

The  INSERT  key  is  programmable.  Inside  the  quotation  marks  of  a 
PRINT  statement,  it  displays  as  II . 

If  you  try  to  program  the  DELETE  key  in  a  PRINT  statement,  you  will 
merely  erase  the  previous  character,  unless  the  DELETE  key  occurs  within  a 
sequence  of  inserted  characters.  The  DELETE  key  may  be  entered  following  an 
INSERT,  but  doing  so  is  not  very  useful.  The  only  common  use  of  this  feature  is 
in  concealing  program  lines  during  a  listing  (to  hide  answers  for  a  test,  for 
instance).  Hidden  data  can  be  easily  rediscovered  in  several  ways,  however,  so 
using  DELETE  characters  within  program  lines  is  not  advisable. 

The  RETURN  character  in  a  PRINT  statement  will  immediately  move  the 
cursor  out  of  the  statement  and  to  the  next  line. 

Data  Entry  (Input) 

Data  entry  should  be  programmed  in  functional  units.  A  mailing-list  pro- 
gram, for  example,  requires  names  and  addresses  to  be  entered  as  data.  You 
should  treat  each  entire  name  and  address  as  a  single  functional  unit,  rather 
than  as  separate  data  items.  In  other  words,  your  program  should  ask  for  the 
name  and  address,  allowing  the  operator  to  enter  all  of  this  information  and 
then  change  any  part  of  it.  When  the  operator  is  satisfied  that  the  name  and 
address  are  correct,  the  program  should  process  the  entire  name  and  address. 
The  program  should  then  ask  for  the  next  name  and  address. 

This  procedure  is  advisable  because  it  is  bad  programming  practice  to 
break  data  input  into  its  smallest  parts.  In  a  mailing-list  program,  for  exam- 
ple, it  would  be  bad  programming  practice  to  ask  for  just  the  name,  process 
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this  data  as  soon  as  it  is  entered,  and  then  ask  for  each  line  of  the  address, 
treating  each  piece  of  the  name  and  address  as  a  separate  functional  unit.  This 
approach  makes  programs  difficult  to  change  and  also  renders  them  less 
readable. 

The  goal  of  any  data  entry  program  should  be  to  make  it  easy  for  an 
operator  to  spot  errors  and  to  give  the  operator  as  many  chances  as  possible  to 
fix  them. 

PROMPTING  MESSAGES 

Any  program  that  requires  data  entry  should  prompt  the  operator  by 
asking  questions.  Questions  are  usually  displayed  on  a  single  line  and  require 
a  simple  response  such  as  "yes"  or  "no."  For  example,  a  prompt  message  such 
as  ANY  CHANGES  (Y  OR  N)?  would  clearly  indicate  the  question  and  the 
available  choices. 

An  operator  responds  to  this  message  by  pressing  the  Y  or  N  key.  Good 
programming  practice  dictates  that  entries  other  than  Y  or  N  not  be  accepted. 
If  the  operator  replies  Y  to  the  ANY  CHANGES  prompt,  another  prompt 
will  display,  such  as  WHAT  ENTRY  LINE  TO  CHANGE  ( 1  -6)?.  In  this  case, 
one  of  six  entry  lines  could  be  changed;  all  the  operator  needs  to  do  is  enter  the 
number  corresponding  to  the  line  that  was  entered  in  error.  Of  course,  with 
this  approach,  each  entry  line  on  the  display  should  have  an  identifying 
number. 

This  type  of  data  entry  should  be  written  in  subroutines,  so  the  main 
program  is  not  clogged  up  with  prompting  messages.  Also,  because  a  limited 
number  of  choices  is  allowed,  a  subroutine  could  contain  the  logic  necessary 
to  check  the  entry  against  permitted  responses. 

Using  subroutines  has  two  implications. 

1.  The  subroutine  must  receive  parameters  from  the  calling  program. 
For  example,  if  a  message  asks  the  operator  to  enter  a  number,  the 
calling  program  should  pass  the  minimum  and  maximum  allowed 
numbers  to  the  subroutine  as  parameters. 

2.  The  subroutine  must  return  the  operator's  response  to  the  calling 
program.  This  variable  may  be  a  character  (for  example, " Y"  or  "N"), 
a  word  (such  as  "yes"  or  "no"),  or  a  number. 

A  subroutine  that  prompts  for  a  reply  of  Y  for  "yes"  or  N  for  "no"  uses  a 
PRINT  statement  to  ask  the  question,  followed  by  a  GET  to  receive  a 
one-character  response.  Since  you  may  have  many  questions  in  a  program 
that  require  a  response  of  "yes  "or  "no,  "the  subroutine  should  also  allow  for  a 
prompt  to  be  passed  to  the  subroutine  from  the  main  program  in  a  string 
variable.  Here  are  the  necessary  statements. 
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3000  REM  flSK  R  QUESTION  AND  RETURN  A  RESPONSE  OF  V  OR 

N  IN  VN* 
3010  PRINT  "H" 

3020  PRINT  "DO  VOU  WANT  TO  MAKE  ANV  CHANGES?  " i 
3030  GET  VN$:    IF  VN$0"N"  AND  VHtC>"V"  THEN  3030 
3040  PRINT  VN* 
3050  RETURN 


The  string  variable  QU$  must  be  set  in  the  program  that  calls  the 
subroutine.  The  subroutine  is  generalized;  that  is,  it  displays  any  prompt  sent 
to  it  by  the  main  program.  The  response  is  returned  to  the  main  program  in 
the  string  variable  YN$. 

Now  consider  dialog  that  allows  an  operator  to  enter  a  number.  Assume 
that  the  main  program  passes  to  the  subroutine  the  lowest  allowable  numeric 
entry  in  LO%  and  the  highest  in  HI%.  Once  the  operator  enters  a  number 
within  range,  the  subroutine  will  return  the  entered  number  in  NM%.  Here  is 
the  subroutine  that  gets  the  keyboard  entry,  checks  it  against  LO%  and  HI% 
values,  and  then  passes  it  back  to  the  main  program  in  NM%. 


3500  REM  ASK  FOR  fl  NUMERIC  SELECTION 
3510  REM  RETURN  THE  NUMBER  IN  NMJ4 
3520  REM  NMX  MUST  BE  O  HV/.  AND  >=  LOJi 
3530  PRINT  QU«; 

3540  GET  C$:IF  CS=U  "  THEN  3540 
3550  NMX*VflL(C$) 

3560  IF  myXLOX  OR  NMX>HIX  THEN  3540 
3570  PRINT  C$; 
3580  RETURN 


Write  a  short  program  that  sets  values  for  HI%  and  LO%,  and  then  goes 
to  subroutine  3500.  Add  the  previous  subroutine  and  run  it. 

Can  you  change  the  subroutine  so  that  it  accepts  two-digit  input?  Try  to 
write  this  modified  program  yourself.  If  you  cannot  do  it,  wait  until  the  next 
section,  where  you  will  find  the  necessary  subroutine  in  the  program  that 
controls  the  input  of  a  date. 


ENTERING  A  VALID  DATE 

At  some  point,  most  programs  need  relatively  simple  data  input  —  more 
than  a  simple  yes  or  no  but  less  than  a  full  screen  display,  a  date  for  example. 
You  must  be  careful  with  such  apparently  simple  data  entry.  In  all  likelihood, 
the  date  will  be  just  one  item  in  a  data  entry  sequence.  If  you  carefully  design 
data  entry  for  each  small  item,  the  operator  will  not  have  to  restart  a  long  data 
entry  sequence  whenever  he  or  she  makes  a  mistake  in  a  single  entry. 

The  date  is  to  be  entered  as  shown  here. 
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MM— DD— YY 


Year 

Separator 

Day  of  the  month 

Separator 

Month 


The  dashes  separating  the  month,  day,  and  year  could  be  slashes  or  any  other 
appropriate  character.  (In  Europe,  the  day  of  the  month  precedes  the  month.) 

You  should  program  data  entry  so  that  the  procedure  is  easy  to  under- 
stand. The  operator  should  be  able  to  see  immediately  where  data  is  to  be 
entered,  what  type  of  data  is  required,  and  how  far  the  data  entry  process  has 
proceeded.  A  good  way  of  showing  where  data  is  to  be  entered  is  to  display 
the  entry  line  in  inverse  video.  For  example,  the  program  that  asks  for  a  date 
might  create  the  following  display: 


You  can  create  such  a  display  with  the  following  statement: 

10  PRINT" <CLR><CRSR1  XCRSR1  >";TAB(20);" <RVS  ON>b£ 
<RVS  OFF>  —  <RVS  ON>  W>  <RVS  OFF>  —  <RVS  ON> 
pp<RVS  OFF>";CHR$(13);"<CRSRt  >";TAB(20); 

£  represents  a  space  code 

This  PRINT  statement  includes  cursor  controls  that  position  the  date  entry  to 
begin  at  column  6  in  row  3.  The  PRINT  statement  also  clears  the  screen  so 
that  no  residual  display  surrounds  the  request  for  a  date.  After  displaying  the 
data  entry  line,  the  PRINT  statement  moves  the  cursor  back  to  the  first 
position  of  the  entry  line  by  using  the  RETURN  and  CRSR  UP  characters, 
followed  by  a  TAB  to  position  6  on  the  current  display  line. 

Try  using  an  INPUT  statement  to  receive  entry  of  the  month.  This  can  be 
done  as  follows: 

20  INPUT  M$; 


■Cursor  flashing  at  entry 
character  position 


Data  must  be  entered  into  these 
character  positions 


Enter  statements  in  lines  10  and  20  as  illustrated,  and  execute  them.  The 
INPUT  statement  will  not  work.  Aside  from  the  fact  that  a  question  mark 
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displaces  the  first  entry  line  character,  the  INPUT  statement  picks  up  the  rest 
of  the  line  following  the  question  mark.  Unless  you  overwrite  the  entire  date 
entry  display — which  requires  entering  a  very  large  number  —  you  will  get  an 
error  message  each  time  you  press  the  RETURN  key,  because  C-128  BASIC  is 
accepting  everything  on  the  line  as  if  it  were  a  keyboard  entry.  This  is  an 
occasion  to  use  the  GET  statement. 


10  PRINT  MXDdti    »-t  ft~fl  ■lNCHR*(13)G"TN 

20  GET  CM 'IF  C$«"  "THEN  20 

30  PRINT  C$1 :MMf«C$ 

40  GET  C$-  IF  CS«"  "THEN  40 

50  PRINT  C$i  ' MMS*MM$+C$ 

60  STOP 


These  statements  accept  two-digit  input.  The  input  displays  in  the  first  part  of 
the  date.  The  two-digit  input  needs  no  RETURN  or  other  terminating  charac- 
ter. The  program  automatically  terminates  the  data  entry  after  two  characters 
are  entered. 

Two-digit  entries  are  needed  for  the  month,  the  day,  and  the  year.  Rather 
than  repeating  statements  in  lines  20  through  50,  you  could  put  these  state- 
ments into  a  subroutine  and  branch  to  it  three  times,  as  follows: 


10  print  "raoM  m-&  *-&  ■";cHRfci3);":r; 

20  G08UB  1000'MMi«TC*:PRINTTRB<3) 
30  GOSU1  1000:DDi-TC$:PRINTTRB(6) 
40  GOSUB  1000: VVi»TC$ 
50  STOP 

1000  REM  TWO  CHRRflCTER  INPUT  SUBROUTINE 
1010  GET  CM  ' IF  C*»""    THEN  1010 
1020  PRINT  Cfi 

1030  GET  CCf:lF  CC§»""  THEN  1030 
1040  PRINT  CCf 
1050  TC*wC*+CCt 
1060  RETURN 


The  variables  MM$,  DD$  and  YY$  hold  the  month,  day,  and  year  entries, 
respectively.  Each  entry  is  held  as  a  two-character  string.  You  should  empty 
the  input  buffer  before  accepting  the  first  input;  otherwise,  any  prior  charac- 
ters in  the  input  buffer  will  be  read  by  the  first  GET  statement  in  the 
two-character  input  subroutine.  You  need  to  empty  the  buffer  only  once 
before  the  first  GET  statement. 

There  are  two  ways  to  help  the  operator  recover  from  errors  made  in 
entering  a  date. 

•  The  program  can  automatically  test  for  valid  month,  day,  and  year 
entries. 

•  The  operator  can  restart  the  data  entry  by  pressing  a  specific  key. 
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The  program  can  check  that  the  month  lies  between  01  and  12.  The 
program  will  not  bother  with  leap  years,  but  will  check  for  the  maximum 
number  of  days  in  the  specified  month.  Any  year  from  00  through  99  is 
allowed.  Any  invalid  entry  restarts  the  entire  date  entry  sequence.  Also,  if  the 
operator  presses  the  RETURN  key,  the  entire  date  entry  sequence  restarts. 

The  final  date  entry  program  is  shown  in  Figure  4  - 1 .  Notice  that  the  date 
is  built  up  in  the  eight-character  string  DT$  as  the  month,  day,  and  year  are 
entered. 

Three  questions  are  asked  of  data  as  it  is  entered. 

•  Is  the  character  a  RETURN? 

•  If  the  character  is  not  a  RETURN,  is  it  a  valid  digit? 

•  Is  the  two-character  combination  a  valid  month  for  the  first  entry,  a 
valid  day  for  the  second  entry,  or  a  valid  year  for  the  third  entry? 

The  RETURN  has  been  selected  as  an  abort  (restart)  character.  By  replac- 
ing CHR$(13)  in  lines  60,  160,  230,  and  1035,  you  can  select  any  other  abort 
character.  When  the  operator  presses  the  selected  abort  key,  the  entire  date 
entry  sequence  restarts.  You  must  check  for  the  abort  character  in  the  two- 
character  input  subroutine  (at  line  1035),  since  you  want  to  abort  after  the  first 
or  second  digit  has  been  entered. 

The  main  program  also  checks  for  an  abort  character  in  order  to  branch 
back  to  the  statement  in  line  10  and  restart  the  entire  date  entry  sequence.  You 
could  branch  out  of  the  two-character  input  subroutine  and  to  the  statement 
in  line  10  in  the  calling  program,  thereby  eliminating  the  abort  character  test 
in  the  calling  program,  but  this  is  a  bad  practice.  Every  subroutine  should  be 
treated  as  a  module,  with  a  specified  entry  point  or  points  and  standard 
subroutine  return  points. 

Using  GOTO  to  branch  between  the  subroutine  and  the  calling  program 
is  likely  to  be  a  source  of  programming  errors.  If  you  branch  out  of  the 
subroutine  and  back  to  the  calling  program  without  going  through  the 
RETURN,  you  are  making  yourself  vulnerable  to  all  kinds  of  subtle  errors  that 
you  will  not  understand  until  you  are  an  experienced  programmer. 

Program  logic  that  tests  for  nondigit  characters  can  reside  entirely  in  the 
two-character  input  subroutine.  This  program  ignores  nondigit  characters. 
Statements  in  lines  1016  and  1036  test  for  nondigit  characters  by  comparing 
the  ASCII  value  of  the  input  character  and  the  ASCII  values  of  the  allowed 
numeric  digits.  Logic  to  check  for  valid  month,  day,  and  year  must  exist 
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5  REM  ROUTINE  TO  ACCEPT  AND  VERIFY  fl  DATE 

10  print  "nmua  m-a  m-a  i";chr*<13:>;":tj 

50  GOSUB  1000: REM  GET  MONTH 

£0  IF  C*=CHR*<13>  OR  CC*»CHR*<13>  THEN  10 

70  DT*»TC*: PRINT  TAB<3) 

80  REM  CHECK  FOR  VALID  MONTH 

90  M5>VAL(TC*> 

95  IF  W/Xl  OR  MJi>12  THEN  10 

100  IF  Mm  OR  M5012  THEN  10 

110  REM  OET  NUMBER  OF  DflVS  IN  MONTH 

120  D»31 

130  IF  M?i»2  THEN  DX»28 

140  IF  MX«4  OR  MJi«6  OR  MJS»9  OR  MX»11  THEN  DK=30 

150  GOSUB  1000:  REM  GET  DAV 

160  IF  CS«CHRS(13)  OR  CC*»CHR*< 13)  THEN  10 

170  DT*«DT*+"-"+TCf : PRINT  TAB<6) 

190  REM  CHECK  FOR  VALID  DAV 

200  IF  VflL<TEt><:i  OR  VALCTC*»DX  THEN  10 

210  OOSUB  1000:  REM  GET  VEAR 

220  DTt*DTf+"-"+TC* 

230  IF  C**CHR*<13>  OR  CCf"CHR*< 13)  THEN  10 
240  REM  CHECK  FOR  VALID  VEAR 
270  STOP 

1000  REM  TWO  CHARACTER  INPUT  SUBROUTINE 

1010  GET  Cf:  IF  Cf-""  THEN  1010 

1011  IF  VAL<Bf»100  THEN  PRINT"T" 

1015  IF  Cf»CHRf<13)  THEN  1050 

1016  IF  Cf<"0"  OR  Cf>"9"  THEN  1010 
1020  PRINT  Cf J 

1030  GET  CCf-IF  CCf"""  THEN  1030 

1035  IF  CC*»CHRSU3)  THEN  1050 

1036  IF  CCf<"0"  OR  CC*>"9"  THEN  1030 
1040  PRINT  CCf i 

1050  TCf»Cf+CCf 
1060  RETURN 


FIGURE  4-1.  A  simple  program  for  entering  and  verifying  a  date 
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within  the  calling  program  because  each  of  these  two-character  values  has 
different  allowed  limits. 

The  statement  in  line  100  tests  for  a  valid  month.  Statements  in  lines  120, 
130,  and  140  compute  the  maximum  allowed  day  for  the  month  entered.  The 
statement  in  line  200  checks  for  a  valid  day.  The  check  for  a  valid  year  in  line 
260  is  very  simple. 

A  numeric  equivalent  of  the  month  is  generated  in  line  90,  but  not  the 
numeric  equivalent  of  the  day  or  the  year.  The  reason  is  that  the  day  and  year 
are  not  used  very  often,  but  the  month  is  used  in  lines  90  through  140.  You  will 
save  both  memory  and  execution  time  by  using  a  numeric  representation  of 
the  month. 

It  does  take  more  time  to  write  a  good  data  entry  program  that  checks  for 
valid  data  input,  allowing  the  operator  to  restart  at  any  time.  Is  the  extra  time 
worthwhile?  By  all  means,  yes.  You  will  write  a  program  once,  while  an 
operator  may  have  to  run  the  program  hundreds  or  thousands  of  times.  Thus, 
by  spending  extra  programming  time  once,  you  may  save  operators  hundreds 
or  thousands  of  delays. 


Formatted  Data  Input 


The  best  way  of  handling  multi-item  data  entry  is  to  display  a  form  and  then 
fill  it  in  as  data  is  entered.  Consider  the  formatted  name-and-address  display 
given  earlier  in  this  chapter. 

ENTER  NAME  AND  REDRESS 


II 

NAME 

m 

STREET 

» 

CITV 

SI 

STATE 

a 

ZIP 

a 

PHONE 

Each  entry  line  has  a  corresponding  number.  The  form  displays  the  number  in 
inverse  video.  The  operator  enters  data  starting  with  item  1  and  ending  with 
item  6.  The  operator  can  then  change  any  specific  data  entry  line. 

The  following  statements  clear  the  screen  and  display  the  initial  form: 

10  REM  NAME  RND  ADDRESS  DATA  ENTRV 

20  REM  DISPLRV  THE  DATA  ENTRV 

30  PRINT  "aHENTER  NAME  AND  ADDRESS" 

40  PRINT  "Ml      NAME: " 

50  PRINT  "321  STREET : " 

60  PRINT  "231  CITV" 

70  PRINT  "SKI  STATED" 

80  PRINT  "351  ZIP:" 

90  PRINT  "flfcl  PHONE:" 
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The  program  listed  in  Figure  4-2  is  a  more  complete  version  of  the 
name-and-address  program.  It  uses  the  display  format  shown  earlier.  Key  in 
the  program  if  you  wish.  The  following  discussion  will  help  you  gain  a  better 
understanding  of  the  program's  structure  and  how  it  works. 

In  order  to  format  the  display  itself,  lines  10  through  90  print  each  entry 
line.  The  RVS  ON  control  character  precedes  each  PRINT  statement  line 
number,  and  the  RVS  OFF  character  follows  it.  These  characters  do  not  display 
anything  by  themselves,  and  they  do  not  take  up  space  on  the  display.  They  do 
change  the  display  mode;  that  is,  any  characters  following  the  RVS  ON  will 
display  in  inverse  video.  Likewise,  any  characters  following  the  RVS  OFF  will 
display  in  normal  video. 


THE  DATA  ENTRY  SEQUENCE 

Once  the  entry  lines  are  displayed,  the  entries  start  at  the  NAME  line. 
The  program  displays  a  black  bar,  showing  where  the  entry  should  start,  as 
well  as  how  long  the  entry  will  be. 

The  operator  can  back  up  on  the  entry  line  by  pressing  the  INS/ del  key 
to  correct  any  typing  errors.  When  the  entry  is  complete,  the  operator  presses 
RETURN  and  the  program  goes  to  the  next  entry  line. 

This  data  entry  sequence  translates  into  the  following  BASIC  statements: 

200  REM  GET  30  CHARACTER  NAME 
210  RX»3  :  CX=9  :  LN5i=30 :  GOSUB  8000 
220  Nfl**CC* 

230  IF  EDITING*!  THEN  500 

250  REM  GET  30  CHARACTER  STREET 

260  RX*4  :  CZ=9 «  LN/i*30 :  GOSUB  8000 

270  SR^^rcs 

280  IF  EDITING?.  THEN  500 
300  REM  GET  30  CHARACTER  CI TV 
310  R'i=5  :  C'/>9  :  LN'/>30  :  GOSUB  8000 
320  CI**CC* 

330  IF  EDITING';!  THEN  500 

350  REM  GET  12  CHARACTER  STATE 

360  R/i=6  :  Ctf=9 :  LN/i=12 :  GOSUB  8000 

370  IF  EDITING*!  THEN  500 

400  REM  GET  5  CHARACTER  ZIP  CODE 

410  R*!*7  =  C*!«9  :  LN*>5  :  GOSUB  8000 

420  2I$=CC$ 

430  IF  EDITINGS  THEN  500 
450  REM  GET  14  CHARACTER  PHONE  NUMBER 
460  R*!=8  :  C*!«9  :  LN/i=14 :  GOSUB  8000 
470  PH*=CC$ 


There  is  some  uniformity  to  these  statements,  which  are  in  six  separate 
groups.  The  groups  start  at  lines  200,  250,  300,  350,  400,  and  450,  each 
corresponding  to  an  entry  the  operator  is  to  make.  Each  group  begins  with  a. 
REM  statement. 
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10  REM  NAME  AND  ADDRESS  DATA  ENTRV 

20  REM  DISPLflV  THE  DATA  ENTRV 

30  PRINT  "mWENTER  NAME  AND  ADDRESS" 

40  PRINT  "fill  NAME:" 

50  PRINT  "321  STREET : " 

60  PRINT  "SfBi  CITV:" 

70  PRINT  "CWi    STATE: " 

80  PRINT  "fiBS       ZIP- " 

90  PRINT  "S61  PHONE:" 

100  EDITING**© 

200  REM  GET  30  CHARACTER  NAME 
210  R*<3 : C**9 : LN*<30 : GOSUB  8000 
220  Nfl*»CC* 

230  IF  EDITING*  THEN  500 
250  REM  GET  30  CHARACTER  STREET 
260  R**4:C*=9:LN*=30: GOSUB  8000 
270  SR**CC* 

280  IF  EDITING*  THEN  500 
300  REM  GET  30  CHARACTER  CITV 
310  R*«5  :  C//>9  :  LN**30  '  GOSUB  8000 
320  CI*«CC* 

330  IF  EDITING*  THEN  500 

350  REM  GET  12  CHARACTER  STATE 

360  R*«6:C*»9:LN**12:GGSUB  8000 

370  IF  EDITING*  THEN  500 

400  REM  GET  5  CHARACTER  ZIP  CODE 

410  R*=7 : C*=9 : LN*«5 : GOSUB  8000 

420  ZI**CC* 

430  IF  EDITING*  THEN  500 

450  REM  GET  14  CHARACTER  PHONE  NUMBER 

460  R**8:C*«9:LN*«14:G0SIJB  8000 

470  PH**CC$ 

500  REM  ASK  IF  ANV  CHANGES  ARE  TO  BE  MADE 

510  EDITING*=-1 

520  R**10:C**0:GGSIJB  9000 

530  QU*="ANV  CHANGES?  II" 

540  GOSUB  3000: REM  GET  "V"  OR  "N" 

550  IF  C*«"N"  THEN  PRINT        '>  :  END 

560  REM  ASK  WHICH  LINES  NEED  CHANGING 

570  QU**" WHICH  LINE  <l-6)?:  II" 

580  R*»12:L0*»1 =HI*«6 

590  GOSUB  3500 

600  ON  NM*  GOTO  200,250,300,350,400,450 
610  GOTO  520 

3000  REM  ASK  A  QUESTION  AND  RETURN  A  RESPONSE  OF  V  OR  N  IN  C$ 
3020  PRINT  QU*.i 

3030  GOSUB  5000: REM  GET  A  CHARACTER 


FIGURE 4-2.  A  name-and-address  entry  program 
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3040 

IF  C*0"V"  AND  C*OnN"  THEN  3030 

3050 

PRINT  cs; 

3060 

RETURN 

3500 

REM  RSK  FOR  fl  NUMBER I C  SELECTION 

3510 

REM  RETURN  SELECTION  IN  NME 

3520 

REM  NMX  MUST  BE  LESS  THAN  MX  AND  MORE  THAN  LOX 

3530 

REM  CALLING  PROGRAM  MUST  SET  HI^LOtf  AND 

QUS, 

THE  QUESTION  ASKED 

3540 

GOSUB  9000: REM  POSITION  THE  CURSOR 

3550 

PRINT  QU* J 

3560 

GOSUB  5000:  REM  GET  A  CHARACTER 

3570 

NMH-VflL<C$) 

3580 

IF  NMX<LQX  OR  NMX>MH  THEN  3560 

3590 

PRINT  C*J 

3600 

RETURN 

5000 

REM  DISPLAV  FLASHING  CURSOR  AND  GET  CHARACTER 

5010 

FOR  1=0  TO  60 

5020 

IF  1=0  THEN  PRINT  "S  SI"; 

5030 

IF  1*30  THEN  PRINT  "  II"; 

5040 

GET  C*:    IF  CSO""  THEN  1=60 

5050 

NEXT  I 

5060 

IF  C*=""  THEN  5000 

5070 

RETURN 

8000 

REM  INPUT  SUBROUTINE 

8020 

SP$»"                                                         " : REM 

30  SPACES 

8040 

GOSUB  9000:   REM  POSITION  THE  CURSOR 

8060 

PRINT  "  Si"  ;  LEFTS  <!SP$;  LN/O  ;  "i"  J 

8070 

GOSUB  9000:   REM  POSITION  THE  CURSOR 

8100 

CC$=" " 

8110 

GET  C$: IF  CS=""  THEN  8110 

8120 

IF  C**CHR*a3)  THEN  8200 

8130 

IF  CS*CHR$<20>  THEN  8160 

8140 

IF  LEN<CC*XLNX  THEN  CC*=CCS+CS :  PRINT  C$; 

8150 

GOTO  8110 

8160 

IF  CCS*""  THEN  8110 

8170 

PRINT  "lid  HI"; 

8175 

REM  DELETE  CHARACTER  FROM  STRING  CCS 

8180 

CCS=LEFTS <  CCS .. LEN  < CCS > - 1 > 

8190 

GOTO  8110 

8200 

IF  LNX>LEN(CCS>  THEN  PRINT  LEFT*<SPS,  LN5i- 

•len<cc*o::«; 

8210 

RETURN 

9000 

REM  CURSOR  POSITIONG  SUBROUTINE 

9010 

9020 

9030 

PRINT  "8";: REM  MOVE  CURSOR  TO  (0,0) 

9040 

PR  I  NT  LEFT*  ( RS ,  RX  ">  j  LEFTS  <  CS  j  CX ) ; 

9050 

RETURN 

9500 

GOSUB  5000 : PRINT  C$;:GOTO  9500 

FIGURE  4-2.  A  name-and-address  entry  program  {continued) 
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Lines  200  through  230  have  the  same  structure  as  the  other  five  statement 
groups. 


200  REM  GET  30  CHARACTER  NAME 
210  RH=3  :  C2=9 :  LN"i=30 :  GOSUB  8088 
220  NA*=CC* 

230  IF  EDITING?*  THEN  500 


Line  210  assigns  values  to  variables  and  performs  a  GOSUB  to  line  8000. 
Line  8000  is  a  data  entry  subroutine;  it  uses  variables  R%  and  C%  to  specify 
where  the  data  entry  will  occur  on  the  screen.  LN%  contains  the  maximum 
length  of  the  entry.  Line  220  assigns  the  entered  data  to  NA$,  the  string 
variable  to  hold  the  name. 

Line  230  is  a  logical  test  that  you  can  ignore  for  now;  it  will  be  explained 
shortly. 

Now  check  the  group  starting  at  line  250.  Although  the  values  assigned 
to  R%,  C%,  and  LN%  may  differ  and  line  270  is  not  exactly  the  same,  the 
structure  of  lines  250-280  is  identical  to  that  of  lines  200-270.  This  is  the  case 
for  all  of  the  other  statement  groups. 


EDITING  DATA  ENTRY  LINES 

Once  all  six  lines  are  entered,  the  program  displays  ANY  CHANGES? 
and  waits  for  a  response  of  Y  or  N.  If  the  response  is  N,  the  program  will  clear 
the  screen  and  end.  If  the  response  is  Y,  the  program  will  ask  which  entry  line 
needs  to  be  changed.  At  this  point,  the  operator  can  change  any  entry  lines  at 
random  until  all  lines  are  correct. 

These  steps  are  performed  by  following  lines  of  the  data  entry  program  in 
Figure  4-2: 


500  REM  ASK  IF  flNV  CHANGES  ARE  TO  BE  MADE 

510  EDITING^-l 

520  RX=10:CX=0: GOSUB  9000 

530  QU*="flNV  CHANGES?  II" 

540  GOSUB  3000 : REM  GET  "V"  OR  "N" 

550  IF  C**"N"  THEN  PRINT        J  : END 

560  REM  ASK  WHICH  LINES  NEED  CHANGING 

570  QU$="WHICH  LINE  <l-6)?:  II" 

580  RH12:L0H*1 :HIX=6 

590  GOSUB  3500 

600  ON  NMX  GOTO  200,250,300,350,400,450 
610  GOTO  520 


Line  510  is  of  special  interest  because  it  "switches  on"  the  editing  process. 
Back  at  line  100,  the  integer  variable  EDITING%  was  set  to  0.  At  the  end  of 
each  statement  group,  the  logical  test  of  EDITING%  would  cause  program 
logic  to  fall  through  to  the  next  group.  Now  that  EDITING%  is  nonzero 
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(equal  to  —  l ),  program  logic  can  randomly  access  each  statement  group,  thus 
allowing  each  entry  line  to  be  changed  in  a  random  fashion. 

Lines  520  through  540  call  the  "yes-or-no"  subroutine;  if  the  operator 
enters  N  in  response  to  ANY  CHANGES?,  the  program  ends.  If  the  operator 
enters  Y,  program  logic  continues. 

Lines  570  and  580  set  variables  for  the  numeric  entry  subroutine,  and  line 
590  calls  it.  The  subroutine  returns  the  number  of  the  entry  line  to  change  ( l , 
2,  3,  4,  5,  or  6)  in  the  integer  variable  NM%,  and  program  logic  proceeds  to 
line  600. 

The  ON-GOTO  statement  on  line  600  uses  the  number  entered  in  NM% 
to  change  one  of  the  six  name-and-address  lines  by  branching  back  to  any  of 
the  six  statement  groups.  EDITING%  plays  a  critical  part  here,  because  the 
logical  test  at  the  end  of  each  statement  group  will  now  cause  a  branch  directly 
to  line  500,  which  is  the  start  of  the  ANY  CHANGES?  routine.  If  EDITING% 
was  zero,  this  would  not  happen.  Program  logic  would  plod  along  to  the  next 
entry  line  unconditionally.  Try  changing  line  510  to  EDITING%=0,  and  note 
the  difference  in  operation. 

DATA  ENTRY  SUBROUTINES 

There  are  six  subroutines  in  this  program.  Each  subroutine  has  a  specific 
function.  One  of  the  subroutines  is  not  used  by  the  main  program  but  is  called 
by  the  other  subroutines. 

First,  look  at  the  subroutine  starting  at  line  3000  and  ending  at  line  3060. 
This  asks  a  question  that  requires  a  Y  or  N  response.  The  subroutine  displays 
the  question  that  was  passed  to  it  in  string  variable  QU$.  It  calls  the  subrou- 
tine at  line  5000,  which  in  turn  gets  a  character  from  the  keyboard.  If  the 
character  is  Y  or  N,  the  subroutine  ends  and  returns  the  response  in  C$. 

3000  REM  ASK  fl  QUESTION  AND  RETURN  R  RESPONSE  OF  V  OR 

N  IN  C* 
3020  PRINT  QU*; 

3030  G0SUB  5000 : REM  GET  fl  CHARACTER 
3040  IF  CtO"V"  AND  C$0"N"  THEN  3030 
3050  PRINT  C*j 
3060  RETURN 

But  why  use  a  subroutine  to  get  a  character  when  a  GET  statement  would 
suffice?  A  GET  statement  checks  the  keyboard  for  a  keypress,  but  it  gives  no 
clear  sign  to  the  operator  that  a  character  should  be  entered.  The  subroutine 
at  line  5000  flashes  the  cursor  while  waiting  for  a  keypress,  thus  making  it 
more  obvious  that  the  C-128  is  waiting  for  some  kind  of  entry.  Besides,  the 
get-character  subroutine  is  used  by  another  subroutine  in  this  program.  It 
makes  sense  to  relegate  this  low-level  function  to  another  subroutine. 
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The  subroutine  starting  at  line  3500  and  ending  at  line  3600  asks  for  a 
single-digit  numeric  entry.  In  the  name-and-address  program,  the  only 
numeric  entry  is  the  number  of  the  line  to  change,  which  ranges  from  1  to  6. 


350*  REM  ASK  FOR  fl  NUMERIC  SELECTION 
3510  REM  RETURN  SELECTION  IN  NMX 

3520  REM  NMH  MUST  BE  LESS  THAN  HI*  AND  MORE  THAN  L0>i 
3530  REM  CALLING  PROGRAM  MUST  SET  HI^LOK  AND  QU$, 

THE  QUESTION  ASKED 
3540  G0SUB  9000 : REM  POSITION  THE  CURSOR 
3550  PRINT  QU$; 

3560  GOSUB  5000    REM  GET  A  CHARACTER 
3570  NM'i=VAL(C$) 

3580  IF  NM"i<L0*  OR  NMX>HIX  THEN  3560 
3590  PRINT  C$; 
3600  RETURN 


This  subroutine  must  have  several  variables  set  by  the  main  program  before  it 
is  called.  First,  the  maximum  and  minimum  allowable  values  of  the  entry 
should  be  in  integer  variables  HI%  and  LO%.  Second,  the  subroutine  displays 
a  question  to  the  operator  contained  in  QU$,  which  also  has  to  be  set  before 
the  subroutine  is  called. 

This  subroutine  moves  the  cursor  to  a  given  screen  position.  The  coordi- 
nates of  that  position  need  to  be  passed  to  the  subroutine  in  the  variables  R% 
and  C%.  Line  3540  calls  the  subroutine  at  line  9000,  which  positions  the 
cursor.  Line  3550  displays  the  prompt,  and  line  3560  calls  the  "get  keyboard 
entry"  subroutine. 

The  subroutine  at  line  5000  needs  no  parameters.  It  simulates  a  flashing 
cursor  while  waiting  for  a  keyboard  entry.  A  FOR-NEXT  statement  on  line 
5010  starts  a  timing  loop  that  displays  an  inverse-video  space  for  the  first  30 
times  through  the  loop.  Once  the  index  variable  I  reaches  30,  the  statement  on 
line  5030  erases  the  cursor.  During  this  time,  the  subroutine  is  constantly 
checking  the  keyboard  for  an  entry.  If  a  key  is  pressed,  the  statement  on  line 
5040  terminates  the  loop  by  setting  I  to  60,  and  the  subroutine  ends,  passing 
back  the  entered  character  in  C$. 


5000  REM  DISPLAY  FLASHING  CURSOR  AND  GET  CHARACTER 

5010  FOR  1=0  TO  60 

5020  IF  1=0  THEN  PRINT  "21  H"j 

5030  IF  1=30  THEN  PRINT  "  11"; 

5040  GET  C*:   IF  MO""  THEN  1=60 

5050  NEXT  I 

5060  IF  Cf=""  THEN  5000 
5070  RETURN 


The  subroutine  starting  at  line  8000  and  ending  at  line  8210  is  designed  to 
position  the  cursor  and  accept  a  string  entry  of  a  specified  length.  This 
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subroutine  therefore  needs  to  know  the  screen  coordinates  (row  and  column) 
of  the  entry  and  the  length  of  the  entry  before  it  can  begin. 

LN%  contains  the  length  of  the  entry  in  characters.  R%  and  C%  contain 
the  row  and  column  of  the  entry.  A  variable  SP$  is  assigned  30  spaces  and  is 
used  at  two  points  in  the  subroutine. 

Next  the  cursor-positioning  subroutine  is  called  by  the  GOSUB  state- 
ment on  line  8040.  Line  8060  prints  the  RVS  ON  character,  followed  by  a  block 
of  inverse-video  spaces  that  show  the  length  of  the  entry  to  the  operator,  and 
then  the  RVS  OFF  character. 


8000  REM  INPUT  SUBROUTINE 

8020  SP*="  " : REM  38  SPACES 

8040  GOSUB  9000:   REM  POSITION  THE  CURSOR 

8060  PRINT  "  EJ"  j  LEFT$(SP$j  LNX)  >  "1"  '> 

8070  GOSUB  9000-.  REM  POSITION  THE  CURSOR 

8100  CC*="" 

8110  GET  C*:IF  C*=""  THEN  8110 
8120  IF  C*=CHR*<13>  THEN  8200 
8130  IF  C*=CHR*<20>  THEN  8160 

8140  IF  LENCCCtXLN*  THEN  CC*=CC$+C$ : PRINT  C$; 

8150  GOTO  8110 

8160  IF  CC$=»M'  THEN  8110 

8170  print  "m  ar; 

8175  REM  DELETE  CHARACTER  FROM  STRING  CC* 
8 1 80  CC**LEFT$  C CC$ , LEN  < CC$ > - 1 ) 
8190  GOTO  8110 

8200  IF  LNH>LEN<CC*>  THEN  PRINT  LEFT*<SP*, LNE-LEN<CC*> > ; 
8210  RETURN 


Statements  on  lines  8100  through  8150  accept  a  character  from  the 
keyboard.  If  the  character  entered  is  RETURN— that  is,  equal  to  CHR$(13)  — 
the  entry  is  complete.  A  branch  to  line  8200  occurs.  Any  part  of  the  black  bar 
on  the  entry  line  disappears,  and  the  subroutine  returns  with  the  full  entry 
contained  in  CCS.  The  subroutine  also  checks  for  the  INS /  DEL  key;  if  this  key 
was  pressed,  the  subroutine  branches  to  line  8170. 

If  the  character  entered  is  neither  RETURN  nor  INS/  DEL,  then  the  charac- 
ter entered  in  C$  is  concatenated  to  CCS,  which  contains  all  of  the  characters 
entered  so  far.  Notice  the  logical  test  on  this  line. 

ei40  IF  LENCCCtKLNJi  THEN  CC*«CC*+C$ •  PRINT  C*J 

If  the  length  of  CCS  is  not  yet  equal  to  the  maximum  number  of  characters 
allowed  for  the  entry  (in  LN%),  then  C$  is  tacked  onto  the  end  of  CCS,  the 
character  entered  is  displayed  on  the  screen,  and  a  branch  back  to  the  GET 
statement  occurs.  If  the  maximum  entry  length  was  reached,  the  character  in 
C$  is  simply  ignored. 

What  do  the  statements  on  lines  8160  through  8190  do?  A  branch  to  these 
statements  occurs  if  the  operator  presses  the  INS/  DEL  key. 
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If  the  operator  presses  INS/ DEL  but  the  entry  string  CCS  is  empty,  then 
no  characters  need  to  be  deleted.  The  IF-THEN  statement  on  line  8160  checks 
for  this  condition  and  branches  back  to  line  8110  if  no  characters  need  to  be 
deleted.  Otherwise,  program  logic  continues  with  line  8170. 

Line  8170  prints  the  CRSR  LEFT  and  RVS  ON  characters  to  position  the 
cursor  on  the  last  character  entered,  a  space  (in  inverse  video)  that  wipes  out 
that  character,  and  then  a  RVS  OFF  and  a  CRSR  LEFT.  What  all  this  does  is 
move  the  cursor  left,  delete  the  last  character  entered,  and  move  the  cursor 
left  once  again  to  the  space. 

Line  8180  deletes  the  last  character  of  CCS  by  measuring  the  length  of 
CCS  with  the  LEN  function,  subtracting  1 ,  and  reassigning  CCS  all  of  its 
original  characters  except  the  last. 

Once  the  character  is  deleted  from  the  screen  and  from  CCS,  the  subrou- 
tine branches  back  to  the  GET  statement  on  line  8110. 

You  should  study  the  name-and-address  program  carefully  to  under- 
stand the  data  entry  aids  that  have  been  included.  They  are  as  follows: 

•  Reversing  the  field  on  the  current  entry  line  clearly  indicates  what  data 
is  expected  and  how  many  characters  are  available. 

•  An  operator  does  not  have  to  fill  in  all  the  characters  on  an  entry  line. 
When  the  operator  presses  the  RETURN  key,  the  balance  of  the  entry  is 
filled  out  with  blanks. 

•  At  any  time,  the  operator  can  backspace  and  correct  errors  on  an  entry 
line  by  pressing  the  INS/ DEL  key. 

•  When  questions  are  asked,  the  program  only  recognizes  meaningful 
responses:  Y  or  N  for  "yes"  or  "no,"  or  a  number  between  1  and  6  to 
select  an  entry  line.  A  data  entry  subroutine  should  ignore  meaningless 
entries.  For  example,  it  should  recognize  Y  for  "yes. "  Recognizing  any 
other  character  could  be  disastrous,  since  accidentally  tapping  a  key 
could  prematurely  take  the  operator  out  of  the  current  data  entry. 

Here  are  some  data  entry  precautions  that  could  be  added. 

•  Check  the  ZIP  code  for  any  nondigit  entry.  However,  postal  codes 
outside  the  U.S.A.  (Canada,  for  example)  do  allow  alphanumeric 
entries. 

•  Many  cautious  programmers  will  program  in  the  prompt  ARE  YOU 
SURE?  when  an  operator  responds  with  "no"  to  the  question  ANY 
CHANGES?.  This  gives  the  operator  who  accidentally  touched  the 
wrong  key  a  second  chance. 

•  You  might  add  a  key  that  aborts  the  current  data  entry  and  restores  the 
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prior  value.  For  example,  if  the  operator  presses  the  wrong  number  to 
select  a  field  that  must  be  changed,  the  example  program  forces  the 
operator  to  reenter  the  line. 

Try  modifying  the  name-and-address  entry  program  to  include  the 
additional  safety  features. 

THE  REAL-TIME  CLOCK 

Another  C-128  computer  feature  is  the  real-time  clock.  This  clock  keeps  real 
time  in  a  24-hour  cycle  by  hours,  minutes,  and  seconds.  The  reserved  string 
variable  TIMES,  or  TI$,  keeps  track  of  the  time. 

Setting  the  Clock 

To  set  the  clock,  use  the  following  format: 

TlMES=uhhmmss" 

where 

hh  is  the  hour  between  0  and  23 
mm  is  the  minutes  between  0  and  59 
ss  is  the  seconds  between  0  and  59 

For  hh,  enter  the  hour  of  the  day  from  00  (12:00  A.M.)  to  23  (11:00  P.M.). 
The  C-128  computer  is  on  a  24-hour  cycle  so  that  you  can  distinguish  between 
A.M.  and  P.M.  The  hours  from  00  to  11  designate  A.M.,  and  the  hours  from  12 
to  23  designate  P.M.,  returning  to  00  at  midnight.  At  midnight,  when  one 
24-hour  cycle  ends  and  another  begins,  hh,  mm,  and  ss  are  all  set  to  zero. 

When  initializing  TIMES  to  the  actual  time,  type  in  a  time  a  few  seconds 
in  the  future.  When  that  actual  time  is  reached,  press  the  RETURN  key  to  set 
the  clock. 

TIME**" 120150" 

Accessing  the  Clcck 

To  retrieve  the  time,  type  the  following  in  immediate  mode: 
?TIME* 

The  computer  will  display  the  time  in  hhmmss  format. 
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?TIMES 
120200 

The  C-128  computer  clock  keeps  time  until  it  is  turned  OFF.  The  clock 
must  be  reset  when  the  computer  is  turned  on  again. 


Real-Time  Clock  Operation 

The  C-128  computer  actually  keeps  track  of  time  in  jiffies.  A  jiffy  is  1  /  60  of  a 
second.  TIME,  or  TI,  is  a  reserved  numeric  variable  that  automatically 
increments  every  1  /  60  of  a  second.  TIME  is  set  to  zero  on  start-up  and  is  set 
back  to  zero  after  51,839,999  jiffies.  TIMES  is  a  string  variable  that  is 
generated  from  TIME.  When  TIMES  is  called,  the  computer  displays  time  in 
hours,  minutes,  and  seconds  (hhmmss)\  that  is,  the  computer  converts  jiffy 
time  to  real  time. 

Notice  that  TIMES  and  TI$  are  not  the  string  representations  of  TIME 
and  TI;  they  are  numbers  representing  real  time,  calculated  from  jiffy  time 
(TIME,  TI).  The  conversion  is  done  as  follows:  each  second  is  divided  into  60 
jiffies;  one  minute  is  composed  of  60  seconds;  and  one  hour  is  made  up  of  60 
minutes.  Thus,  one  second  is  60  jiffies,  one  minute  is  3600 jiffies,  and  one  hour 
is  216,000  jiffies,  as  illustrated. 


Jiffy 

=  1 

-  60  X  Jiffy 

=  60  Jiffies 

Second/  60  =  Jiffy 


Minute    =  60  X  Second 

=  60  X  (60  Jiffies) 
=  3600  Jiffies 


Minute/ 60=  Second/ 60=  Jiffy 


Hour       =  60  X  Minute 

=  60  X  (3600  Jiffies) 
=  216,000  Jiffies 


Hour/60  =  Minute/60  =  Second/60  =  Jiffy 


The  following  program  converts  jiffy  time  (J)  into  real  time,  shown  as 
hours  (H),  minutes  (M),  and  seconds  (S).  A  complete  program  follows  the 
statement  descriptions. 


10  J*TI 

20  H«INT<J/21SB00) 


Calculate  hours.  Integer  function 
takes  only  whole  number 
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30  IF  HO0  THEN  J=J-H*216000  If  any  hours,  subtract  number  of 

jiffies  in  one  hour  by  H  to  leave 
remaining  jiffies 


40  M= I NT (J/3600) 

50  IF  MO0  THEN  J=J-M*3600 
€0  S= I NT (J/60) 


Calculate  minutes. 

Integer  function  takes  only  whole 

number 

If  any  minutes,  subtract  number  of 
jiffies  in  minutes  by  7  to  leave 
remaining  jiffies 

Calculate  seconds.  Integer  function 
takes  only  whole  number 


5  PRINTMn?ERL  TIME"  :  PRINT  •'  PRINT 

10  J-TI 

15  T$*TIME$ 

20  H* I NT (J/26000) 

30  IF  HO0  THEN  J=J-H*2 16000 

40  M* I NT (J/3600) 

50  IF  MO0  .THEN  J-J-M-3600 

60  S* I NT (J/60) 

70 -HS*R I GHTS ( STR$ ( H ) > 2 ) 

80  M**RIGHT*(STR*(M),2) 

90  S$*RIGHTS(STR$(S),2) 

100  PR I NT "H  :  M  •  S  :    "  j  H$  >  "  :  11  j  M$  J  11  j  S'$ 

105  PRINT"TIME$ :   " il$ 
110  PRINT  H  attWW"  ;  :  GOTO  10 


In  this  program,  statements  70  through  90  convert  the  numeric  answers 
into  proper  form  for  tidy  printing.  Statement  100  prints  both  the  real  time 
calculated  from  the  program,  and  TIMES,  the  real  time  calculated  automati- 
cally by  the- computer.  Notice  that  the  result  is  the  same  in  both  cases. 

To  get  an  idea  of  jiffy  speed  and  the  conversion  from  the  jiffy  clock  to  the 
standard  clock,  type  in  the  following  program,  which  displays  the  running 
time  of  both  TIMES  and  TIME(TI): 

5  REM  **RUNNING  CLOCKS** 

10  PRINT'TFERL  TIME:    »: PRINT = PRINT" JIFFV  TIME : " 

20  FOR  1=1  TO  235959 

30  : PRINT" S";TflB< 13); TIME* 

40  :F0R  J=l  TO  60  STEP  2 

50   :  PRINT"  WW";  TAB  <  12);  TI 

60  -NEXT 

70  NEXT 
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The  FOR-NEXT  loop  for  TIME  in  line  40  increments  by  STEP  2  (every 
two  jiffies)  for  the  following  reasons: 

•  Displaying  60  jiffies  a  second  is  too  fast  to  read,  and 

•  Displaying  a  jiffy  takes  longer  than  incrementing  the  jiffy.  This  delays 
the  loop,  so  the  TIMES  display  is  slower  than  it  should  be.  By 
incrementing  and  printing  every  other  jiffy,  you  can  minimize  this 
delay  problem.  Run  this  program  and  you  will  see  that  jiffies  incre- 
ment to  60  within  each  second.  Run  this  program  without  STEP  2  in 
line  40  and  see  the  time  delay  when  printing  TIMES. 

Realtime:  006604 
Jiffy  time:  25500 

Keeping  time  in  jiffies  is  useful  for  timing  program  speed.  This  lets  you 
test  the  efficiency  of  a  program.  Consider  the  following  short  program: 

10  PR I NT " r>*KEVB0flRD  TEST**" : PRINT 
20  FOR  1=32  TO  127 
30  PRINT  CHR$<I>; 
40  NEXT  I 

50  FOR  J=161  TO  255 
60  PRINT  CHR*<J>; 
70  NEXT  J 

80  PRINT  :  PRINT  :  PR  I  NT  "MEND  TEST**" 


You  can  compute  execution  time  for  this  program  as  follows: 

1.  TI  (or  TIME)  is  assigned  to  a  variable  at  the  start  of  the  time  test. 

2.  TI  (or  TIME)  is  checked  at  the  end  of  the  time  test.  Subtract  the  first 
value  of  TI  from  the  new  TI  value.  This  will  give  you  the  amount  of 
jiffy  time  it  took  to  process  the  program  in  question. 

The  following  listing  adds  these  steps: 

10  PRINT  "SMKEVBOflRD  TEST**"  :  PRINT 
15  fl^TI 

20  FOR  1=32  TO  127 
30  PRINT  CHR*<I>; 
40  NEXT 

50  FOR  J- 161  TO  255 
60  PRINT  CHR*<J>; 
70  NEXT 

80  PR I NT: PR  I  NT: PR I NT "••END  TEST**" 
100  PRINT :PRINT"TI  =  ";TI-fl 


As  the  program  continues,  TI  increments  60  times  every  second.  Line  100 
subtracts  the  first  value  of  TI(A)  from  TPs  latest  value.  It  took  41  jiffies  to 
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display  the  keyboard  characters.  Divide  jiffy  time  (41  jiffies)  by  60  (the 
number  of  jiffies  in  a  second). 

41/60  =  0.6833 
Thus,  it  took  0.6833  second  to  run  the  program. 

RANDOM  NUMBERS 

Random  numbers  may  be  used  in  games  you  program  on  your  C-128;  they 
have  more  practical  uses  in  statistics  and  other  applications  as  well.  The  C-128 
will  generate  random  numbers  with  the  RND  function. 

RND  provides  a  real  number  between  0  and  1 .  This  number  is  actually 
pseudo-random;  that  is,  it  is  not  truly  random.  However,  that  is  a  point  raised 
by  statisticians.  The  number  is  a  close  approximation  of  randomness. 

To  determine  the  degree  of  randomness  the  RND  function  will  have,  you 
provide  a  starting  number,  or  seed.  If  you  use  zero  as  the  seed  —  that  is, 
RND(O)  —  the  values  RND  generates  are  based  on  three  separate  internal 
clocks.  The  odds  against  all  three  clocks  having  the  same  values  twice  in  a  row 
are  very  high;  therefore,  any  number  generated  can  be  considered  random. 

The  sequence  of  most  random  numbers  generated  will  always  be  the 
same.  The  only  exceptions  are  RND(O)  and  RND(TI).  Numbers  that  are  very 
nearly  random  may  be  obtained  with  a  random  seed  of  0.  A  predictable 
pattern  of  numbers  may  be  obtained  by  using  a  negative  number  as  a  seed. 

It  may  not  seem  very  useful  to  generate  random  numbers  from  such  a 
small  range  of  values.  To  obtain  larger  numbers,  multiply  the  random 
number  by  the  maximum  value  you  want.  For  instance,  to  get  a  random 
number  between  0  and  100,  multiply  the  random  number  by  100.  Type  in  the 
following  program: 

1  REM  RANDOM 

5  X»100:REM  MULTIPLIER  TO  SET  MAXIMUM  RANGE 
10  R1«RND<0) : REM  GET  RANDOM  NUMBER 

20  R2=X*Rl:REM  MULTIPLV  TO  DESIRED  RANGE  OF  NUMBERS 
50  PRINT"  RAW  #";R1 
55  PR I NT "RANGED  #";R2 

Type  RUN  and  press  the  RETURN  key.  The  computer  will  choose  a  "raw" 
or  random  number,  multiply  it  by  100,  and  display  it. 

RAW      #  .672457317 
RANGED  #  67.2457317 
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Set  X  to  a  positive  number  less  than  100;  then  type  RUN  to  see  a  different 
ranged  number.  Try  setting  X  to  any  negative  real  number  and  running  the 
program  again.  This  gives  you  a  negative  random  number  with  zero  as  the 
greatest  possible  value. 

If  you  need  to  round  the  result  to  the  nearest  whole  or  decimal  number, 
add  the  following  lines  to  the  program  you  just  entered: 

2  Y«3:REM  DECIMAL  DIGITS  WANTED  IN  NUMBER 

30  R3*INT<X*R1+.5):REM  ROUND  TO  NEAREST  WHOLE  NUMBER 

40  R4aINT<X*Rl#l01Y.5>/l01Y:REM  ROUND  TO  V  DECIMAL 

PLACES' 
50  PRINT"  RAW  #";R1 
55  PR I NT "RANGED  #»;R2 
60  PR I NT" ROUNDED  ";R3 
65  PR I NT "ROUNDED  DECIMAL" J R4 

The  variable  Y  controls  the  number  of  decimal  digits  of  precision  in  the 
rounded  decimal  number.  Your  results  will  be  similar  to  the  following: 

RAW  #  .672457317 
RANGED  #  67.2457317 
ROUNDED  67 

ROUNDED  DECIMAL  67.246 

Generating  Random 
Dice  Throws 

Random  numbers  are  generated  in  the  range  0  through  not  quite  1  (the  limit 
of  1,  in  calculus  terms).  You  will  have  to  convert  the  random  number  to 
whatever  range  you  require.  Suppose  numbers  must  range  from  1  to  6  (as  in 
one  die  number  of  a  dice  game).  You  will  need  to  multiply  the  random  number 
by  6. 

6*RND(1) 

This  returns  a  real  number  in  a  range  just  greater  than  0  but  less  than  6.  Add  1 
to  get  a  number  between  1  and  6. 

6*RND(1)+  1 

Then  convert  the  number  to  an  integer.  This  discards  any  fractional  part  of  a 
number,  returning  the  number  in  the  range  1  to  6  but  in  integer  form.  To  do 
this,  you  can  use  either 

INT(6*RND(0)+  1) 

or 


ADVANCED  BASIC  PROGRAMMING  149 


A%=6*RND(0)+  1 

The  general  cases  for  converting  the  RND  fraction  to  whole-number 
ranges  are  shown  here. 

INT(RND(0)*N)  Range  0  to  N 

INT(RND(0)*N+1)  Range  1  to  N 

INT(RND(0)*N+M)  Range  M  to  N 

Now  experiment  with  a  variety  of  different  random-number  ranges  by  modi- 
fying the  statements  given  here. 

The  next  program  shows  — TI  being  used  to  generate  a  random  seed. 
This  program  calculates  numbers  in  the  range  M  to  N.  In  this  program,  the 
values  of  M  and  N  are  set  in  line  10  for  a  given  program  run.  Note  that  these 
values  can  be  negative.  In  the  following  example,  the  display  is  an  unending 
sequence  of  random  numbers  between  —50  and  +50.  (Press  the  STOP  key  to 
end  the  program.)  A  different  sequence  of  numbers  will  be  printed  each  time 
the  program  runs,  since  — TI  provides  a  random  seed.  Note  that  the  X  value 
returned  from  RND(— TI)  is  displayed  instead  of  the  TI  value. 

10  M=50 : N=50 

20  X«RND<-TI> : PRINT  X 

30  FOR  1=1  TO  8 

40  :CX*<N-M+1)*RND<1)+M 

50  ; PRINT 

60  GOTO  30 "REM  PRINTS  NEW  RANDOM  NUMBERS 
RUN 

8.27633085E-06 
-14 

29 
7 

35 
-32 
-12 

48 
-18 

To  illustrate  different  number  ranges,  change  the  values  of  M  and  N  in 
line  10  of  this  program.  For  example,  make  M  =  1  and  N  =  6;  this  will 
generate  an  unending  sequence  of  random  numbers  between  1  and  6. 

Random  Selection 
Of  Playing  Cards 

A  quick  scan  of  the  display  given  in  the  last  section  shows  that  numbers  repeat 
within  the  first  100  generated:  that  is,  101  numbers  will  not  include  every 
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number  in  the  range  —50  to  +50.  This  is  fine  in,  say,  a  dice  game,  but  for  other 
applications  you  may  need  to  produce  random  numbers  in  a  certain  range  so 
that  every  number  occurs  once  and  there  are  no  duplications.  Dealing  from  a 
deck  of  cards  is  one  such  application.  Once  a  card  has  been  selected,  it  cannot 
be  selected  again  during  the  same  deal. 

The  next  program  shows  one  way  of  programming  the  C-128  to  shuffle  a 
deck  of  cards.  This  program  fills  a  52-element  table  D%  with  the  numbers  1 
through  52  in  a  random  sequence.  (Element  D%(0)  is  not  used.)  The  cards  can 
be  pegged  to  the  random  numbers  in  any  way,  such  as 

A=  1 ,  2=2,  3=3,  . . . ,  Q=  12,  K=  13 

Spades=0,  Hearts=13,  Diamonds=26,  Clubs=42 

With  this  scheme,  the  Ace  of  Spades  =1+0=1,  the  Queen  of  Spades  =  12  + 
0  =  12,  the  Three  of  Hearts  =  3  +  13  =  16,  and  so  on. 

In  the  shuffle  program,  a  52-element  flag  table  FL  keeps  track  of 
whether  a  card  has  been  chosen.  PRINT  statements  are  inserted  to  display  the 
seed  value,  followed  by  the  numbers,  in  a  continuous-line  format.  Note  that 
exactly  52  numbers  are  displayed  and  that  no  number  is  repeated.  Each 
program  run  will  produce  a  new  random  sequence. 


10  DIM  RCS3) 
20  E«52 

30  FOR  R«0  TO  51 
40  fl<R)-R 
30  NEXT  R 
60  B-INT(RND(0)*E) 
70  PRINT  R(B), 
80  FOR  R-B  TO  E 
90  A<R>»RCR+1) 
100  NEXT  R 
110  E-E-l 

120  IF  E>0  THEN  60 
RUN 

43  25 
13  3 
5  38 
1  27 
46 

8  21 
36  6 

11  17 


39  10  4  18 

37  15  35  45 

0  33  34  40 

22  48  23  16 

7  32  26  30 

47  9  2  28 

51  29  44  19 

24  12  50  20 


You  will  find  several  uses  for  random  numbers  in  the  programs  you  write, 
especially  if  you  write  game  programs.  In  the  next  two  chapters,  you  will  see 
how  to  utilize  your  C-128's  capabilities  as  a  game  machine. 


CHAPTER 


Game 
Controllers 


The  programs  in  previous  chapters  communicate  with  the  user  in  a  "stop  and 
go"  fashion;  that  is,  they  stop  and  wait  for  the  user  to  type  something  at  the 
keyboard,  and  then  act  upon  it.  This  is  fine  for  balancing  a  checkbook  or 
typing  letters,  but  many  C-128  applications  require  a  different  style  of  com- 
munication. For  example,  a  program  that  simulates  a  aircraft  wouldn't  be 
realistic  if  the  plane  stopped  in  midair  while  the  "pilot"  typed  instructions.  To 
make  this  type  of  program  more  realistic  (and  less  tedious  to  use),  the  C-128 
can  take  its  directions  from  a  different  source.  Instead  of  receiving  instruc- 
tions through  the  keyboard,  the  C-128  can  use  game  controllers,  the  joystick 
and  paddle  controllers  similar  to  those  used  in  arcade  games. 

This  chapter  shows  you  how  to  write  programs  that  use  these  game 
controllers.  It  will  also  describe  how  to  use  the  keyboard  "on  the  run," 
without  going  through  the  stop  and  wait  steps.  If  you  don't  have  a  joystick,  a 
keyboard  example  shows  how  you  can  simulate  one. 
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THE  JOYSTICK  CONTROLLER 

The  joystick,  like  old-fashioned  airplane  control  sticks,  controls  both  up- 
and-down  and  side-to-side  motions.  It  does  so  with  four  switches:  Up,  Down, 
Left  and  Right.  Inside  the  joystick  are  "fingers"  that  push  these  switches  as  the 
stick  is  moved. 


If  the  stick  is  moved  up,  down,  or  to  one  side,  only  one  switch  is  closed. 
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There  is  also  a  Fire  button,  which  has  its  own  switch.  If  you  use  the 
method  described  in  the  following  sections,  your  program  can  tell  whether 
these  switches  are  open  or  closed  and  thus  determine  which  way  the  j  oystick  is 
pointing.  By  moving  the  joystick,  you  can  direct  elements  on  the  screen. 


The  VIA  Chips 

The  joystick  is  connected  to  the  C-128  through  integrated  circuits  called 
Versatile  Interface  Adapters  (VI  As).  Certain  pins  of  the  VIA  chips  connect  to 
the  "outside  world"  through  the  joystick  connectors  at  the  side  of  the  comput- 
er. These  pins  receive  a  signal  sent  to  them  (input)  or  send  a  signal  out  to 
another  device  (output).  Circuitry  in  the  VIA  chip  enables  the  C-128  to  set  or 
examine  the  signals  on  these  pins  by  using  memory  locations.  In  C-64  mode 
the  signals  must  be  read  and  controlled  through  PEEKs  and  POKEs  in 
BASIC. 

Although  the  techniques  of  reading  the  joysticks  are  the  same  for  both 
the  C-64  and  the  C-128,  reading  the  joysticks  in  C-128  mode  can  be  much 
easier  than  it  is  in  C-64  mode.  The  reason  is  that  the  C-128  has  a  single  BASIC 
command^JOY,  that  reads  the  joysticks.  However,  since  the  programming 
techniques  are  basically  the  same  for  both  modes,  the  way  that  the  process 
works  will  be  studied  first,  and  the  differences  between  the  two  modes  will  be 
examined  later. 


Testing  the  Joystick  Switches 

The  VI  A's  input/  output  pins  are  divided  into  two  groups  of  eight.  Each  group 
can  be  set  or  examined  through  a  single  memory  location,  with  one  bit  in  that 
location  representing  each  pin.  The  switches  for  control  port  1  are  connected 
to  one  group  of  pins,  and  the  switches  for  control  port  2  are  in  another  group. 


Memory 
Location 

56320 


Control  Port  1 
Bits 


16 


Up 

Down 
Left 
Right 
Fire 
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Memory 
Location 

56321 


Control  Port  2 
Bits 


16 


•Up 

■  Down 

■  Left 

■  Right 

■  Fire 


Since  the  four  direction  switches  and  the  Fire  button  are  in  the  same 
memory  location,  the  numbers  in  the  boxes  shown  in  the  illustration  are  used 
with  the  AND  operator  to  isolate  the  bit  for  a  particular  switch  from  the 
others  PEEKed  from  the  same  memory  location.  (This  use  of  AND  was 
discussed  in  the  "Boolean  Operators"  section  in  Chapter  3.)  In  the  result  of 
the  AND  operation,  all  bits  except  the  one  you  want  to  look  at  will  be  forced 
to  a  0  value.  (This  is  called  masking.  Just  as  you  use  masking  tape  to  cover  up 
woodwork  while  painting  walls,  computer  programs  use  bit  masks  to  cover 
up  the  bits  they  don't  want  to  test.)  For  example,  the  following  statement 
determines  if  the  Fire  button  of  control  port  1  is  being  pushed: 

10  FB  =  < PEEK < 56320)  AND  16)  =  0 

AND  16  eliminates  the  other  switch  values  by  "covering  up"  all  bits  except  16. 
The  program  then  compares  the  result  to  0.  The  joystick  switches  supply  a  0 
signal  to  their  VIA  pins  when  the  switch  is  closed  and  a  1  when  open.  When 
the  switch  is  closed,  the  button  is  being  pushed. 
Let  us  look  at  the  AND  operation  in  binary. 


PEEK  location  56320  00000 1 1 0 

AND  bit  number  16  0000 1 000 


00000000 


The  result  of  the  AND  is  0,  since  1  AND  0  is  always  0.  The  switch  is  closed,  the 
signal  is  0,  and  the  button  is  pushed. 

Try  entering  and  running  the  following  program  to  see  how  moving  the 
joystick  affects  location  56320: 

10  PRINT  PEEK < 56320) 

20  FOR  1=1  TO  250  :  NEXT  I   :  REM  WRIT  ABOUT  HRLF  R 

SECOND 
30  GOTO  10 
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The  program  checks  and  displays  the  value  in  memory  location  56320  every 
half  second.  As  you  move  the  joystick,  notice  the  changes  in  the  values 
displayed  on  the  screen.  When  a  switch  in  the  joystick  is  closed,  its  mask  value 
(16, 8, 4, 2,  or  1)  is  subtracted  from  the  displayed  number.  To  look  at  the  other 
joystick,  replace  56320  in  line  10  with  56321. 

A  Complete  Joystick  Scanner 

You  will  now  study  the  programming  necessary  to  convert  the  joystick's  bit 
locations  to  physical  movement.  If  you  write  one  program  that  uses  a  joystick, 
you  will  probably  write  others;  so  this  section  includes  a  standard  subroutine 
that  can  be  typed  into  any  program.  This  subroutine  sets  three  variables  for 
the  main  program. 

XI       X  Increment:  controls  movement  to  the  right  or  left 
YI        Y  Increment:  controls  movement  up  or  down 
FB       Tells  whether  the  Fire  button  was  pressed 

XI  is  set  to  —1  for  left,  +1  for  right,  and  0  for  neither.  YI  is  set  to  —1  for 
down,  + 1  for  up,  and  0  for  neither.  If  the  Fire  button  is  pressed,  FB  will  be  a  1 ; 
otherwise,  it  will  be  a  0. 

63000  XTJi  =  PEEK  (56320)  AND  31 
63020  XI  *  SGN<XTX  AND  4)  -  SGN<XTJi  AND  8) 
63030  VI  *  SGNCXTX  AND  2)  -  SGNCXTK  AND  1) 
63040  FB  =  1  -  SGN(XTX  AND  16) 

This  program  uses  some  tricks  to  make  it  run  faster.  Here  is  a  line-by-line 
analysis  of  its  operation. 

63000  reads  the  joystick  in  control  port  1  and  uses  the  technique 
described  above  to  preserve  the  keyboard  scanner 

63020       these  two  lines  derive  the  X  and  Y  increments  from 

63030  the  switch  values.  The  SGN  function  is  used  to  reduce  the 
amount  of  time  needed  to  calculate  them.  This  returns  a  1  if 
the  switch  is  off  and  a  0  if  it  is  on.  This  is  faster  than  comparing 
the  result  of  the  AND  to  zero 

63040       gets  the  value  of  the  Fire  button 

63050       returns  to  the  main  program 
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USING  THE  JOYSTICK  SCANNER 

The  following  simple  program  illustrates  the  capabilities  of  the  joystick 
scanner.  It  moves  an  object  around  on  the  screen  in  response  to  the  movement 
of  the  stick. 

100  PRINT  "ar; 
200  QOSUB  63000 
300  IF  XI«0  AND  VI«0  THEN  200 

400  PRINT  CHR*<20>;    :  REM  DELETE  CHAR  ON  SCREEN 

500  IF  XI  — 1  THEN  PRINT 

£00  IF  XI«  1  THEN  PRINT  "MM H  i 

700  IF  VI  — 1  THEN  PRINT  "Hi"; 

800  IF  VI«  1  THEN  PRINT  "nTj 

900  GOTO  200 


Reading  the  Joysticks 
In  C-128  Mode 

Although  you  can  read  the  joysticks  in  C-128  mode  using  the  PEEKs  and 
POKEs  just  covered,  the  C-128  has  a  special  BASIC  function  that  reads  and 
interprets  the  joysticks  for  you  —  JOY.  Actually  there  are  two  JOY  com- 
mands: JOY(l)  and  JOY(2).  JOY(l)  reads  joystick  l  and  JOY(2)  reads  joy- 
stick 2. 

As  an  example,  read  joystick  l.  To  do  this,  enter  the  line 

PRINT  JOY(l) 

The  number  that  is  printed  determines  the  direction  the  joystick  is  pointing. 
The  direction  values  are 


0  = 

centered  (no  movement) 

1  = 

UP 

2  = 

UP/ RIGHT 

3  = 

RIGHT 

4  = 

DOWN/ RIGHT 

5  = 

DOWN 

6  = 

DOWN/ LEFT 

7  = 

LEFT 

8  = 

UP/ LEFT 

If  the  Fire  button  is  pressed,  these  numbers  will  be  increased  by  128.  For 
example,  if  you  are  pointing  up  and  press  the  Fire  button  at  the  same  time,  the 
number  that  JOY(l)  will  return  is  129. 
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Try  rewriting  the  programs  in  the  last  section  to  use  the  JOY  commands. 
They  will  not  only  be  simpler  to  write,  but  they  will  also  run  faster  because  the 
JOY  function  is  much  faster  than  PEEK  and  POKE. 


The  paddle  controllers  derive  their  name  from  their  use  in  the  early  ping- 
pong-style  video  games.  Each  controller  consists  of  a  variable  resistor  called  a 
potentiometer,  or  pot.  The  potentiometer  is  controlled  by  a  knob  and  a  switch 
similar  to  the  Fire  button  on  the  joystick.  Like  the  joystick,  the  paddle 
interface  is  compatible  with  controllers  made  by  many  video  game 
manufacturers. 

The  value  of  the  pot  is  read  by  the  SID  chip  in  the  C-128  and  converted  to 
a  number  between  0  and  255.  The  switches,  on  the  other  hand,  are  read  by  the 
VI  As,  using  two  of  the  joystick  pins.  (Table  5  - 1  lists  the  location  and  contents 
of  paddle  control  memory.) 

Before  you  can  read  the  values  of  the  four  pots,  you  will  need  to  disable 
the  keyboard  scanner.  You  can  do  this  by  using  a  simple  2-byte  machine 
language  routine.  Then,  when  you  need  to  read  the  paddles,  just  SYS  to  your 
routine  and  read  the  paddles.  NOTE:  You  must  perform  the  SYS  and  read  the 
paddles  in  the  same  BASIC  line,  or  else  the  keyboard  scanner  will  be 
re-enabled. 

The  following  routine  will  read  the  four  paddle  values  and  assign  them  to 
variables  A,  B,  C,  and  D: 

10  PRINT  11  <CLERR/HOME> " 

20  POKE  8000,    120  :  POKE  8001,  S£ 

30  SVS  8000   :  POKE  56320,  64  :  R«PEEK(54297>  :  B=PEEK<54298) 
40  SVS  8000  :   POKE  56320,   128  :  OPEEKC54297)  :  D=PEEK< 54298) 

The  Fire  buttons  on  the  paddle  controllers  can  be  read  from  locations 
56320  and  56321.  If  you  add  these  locations  to  the  following  routine,  the 

TABLE  5-1.  Paddle  Controller  Memory  Locations 


THE  PADDLE  CONTROLLERS 


Location 


Contents 


54279 
54298 
56320 
5632! 


Left  paddle  position 
Right  paddle  position 
Paddles  A&B  Fire  buttons 
Paddles  C&D  Fire  buttons 
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variables  FA,  FB,  FC,  and  FD  will  indicate  whether  the  Fire  buttons  are 
being  pressed.  A  zero  indicates  that  the  button  is  being  pressed. 

70  Ffl  =  SON < PEEK <S6320)  AND  4) 
80  FB  ■  SON (PEEK (56320)  AND  8) 
90  FC  *  SON < PEEK C 36321)  AND  4) 

100  FD  =  SON (PEEK (56321)  AND  8) 

The  C-128  also  has  a  paddle-controller  command  called  POT  that  works 
much  like  the  JOY  command.  Since  the  C-128  can  use  up  to  four  paddles, 
there  are  four  POT  commands:  POT(l),  POT(2),  POT(3),  and  POT(4). 

When  the  C-128  reads  the  POT  command,  the  number  you  get  back  will 
be  in  the  range  0-255  if  the  Fire  button  is  not  depressed.  This  will  give  you  the 
relative  position  of  the  paddle.  If  the  value  is  over  255,  then  you  can  subtract 
the  value  from  256  to  get  the  actual  paddle  position  (and  to  find  out  whether  a 
Fire  button  is  pressed). 

Like  the  JOY  commands,  the  POT  commands  are  not  only  simpler  to 
use  but  will  make  your  programs  run  faster  as  well. 

KEYBOARD  COMMUNICATION 
USING  THE  GET  STATEMENT 

Chapter  3  introduced  the  GET  and  INPUT  statements.  Many  of  the  examples 
so  far  have  used  the  INPUT  statement.  Those  programs  are  the  "stop  and  go" 
kind;  if  they  need  information  from  the  keyboard,  they  have  to  wait  for  it.  If 
you  want  to  write  an  "action"  program  that  receives  instructions  from  the 
keyboard,  you  will  want  to  use  the  GET  statement  instead. 

Like  INPUT,  the  GET  statement  reads  information  from  the  keyboard. 
But  that's  where  the  similarity  ends.  The  main  differences  are  as  follows: 

1 .  INPUT  reads  one  or  more  complete  numbers  or  strings.  GET  reads 
only  a  single  keystroke. 

2.  A  program  using  INPUT  waits  for  you  to  press  RETURN.  If  nothing  is 
typed,  your  program  will  wait  indefinitely.  There  is  no  waiting  with 
GET,  however;  if  no  key  is  pressed,  the  program  tells  you  so  but  keeps 
on  running. 

3.  When  you  are  typing  a  response  to  an  INPUT  statement,  the  ? 
prompts  you  for  input,  and  the  characters  you  type  appear  on  the 
screen.  GET  has  no  prompt  and  doesn't  echo  what  you  type. 

Therefore,  with  a  GET  statement,  a  program  can  determine  whether  a 
key  has  been  pressed  but  won't  wait  if  no  key  is  pressed.  If  the  person  using  the 
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program  types  nothing,  the  program  can  determine  this  and  make  decisions 
based  on  it. 

GET  Statement  Syntax 

The  syntax  of  GET  is  quite  simple: 

GET  variable  name 

No  options  are  available.  You  must  have  exactly  one  variable  in  the  "list." 
Unlike  INPUT,  GET  does  not  allow  a  prompt  string.  You  can,  however,  easily 
display  a  prompt  string:  use  a  PRINT  statement  terminated  with  a  semicolon 
to  stop  the  C-128  from  printing  a  RETURN. 

10  PRINT  "THIS  IS  fl  PROMPT: % 
20  GET  fl$ 

The  variable  used  with  GET  can  be  of  any  type  (integer,  floating  point,  or 
string),  but  a  string  variable  works  best.  There  are  two  reasons  for  this. 

1.  If  a  numeric  variable  is  used,  BASIC  attempts  to  interpret  any  key 
pressed  as  a  number.  If  you  type  something  other  than  a  number,  a 
syntax  error  occurs  and  the  program  stops. 

2.  If  no  key  has  been  pressed,  the  numeric  variable  is  assigned  a  value  of 
0.  The  program  has  no  way  of  determining  whether  a  key  was  pressed 
or  a  0  was  typed. 

With  a  string  variable,  you  can  GET  almost  any  key,  including  the  cursor 
control  keys  and  RETURN.  (The  STOP  and  RESTORE  keys  cannot  be  read,  and 
the  various  shifts  and  the  CTRL  key  operate  as  usual.)  If  no  key  is  pressed, 
GET  assigns  an  empty  string  to  the  variable  and  your  program  detects  this.  If 
you  want  to  wait  until  something  is  typed  in,  use  a  line  like  this: 

10  GET  fi$   :    IF  fll  s  ,M*  THEN  10 

Notice  that  there  is  no  space  between  the  quotes,  resulting  in  an  empty  string. 
If  the  variable  you  GET  is  equal  to  this  empty  string,  then  no  key  was  pressed. 

Echoing  Keystrokes 

As  mentioned  earlier,  characters  entered  with  GET  do  not  appear  on  the 
screen.  Sometimes,  however,  you  need  to  see  what  you  type.  This  can  be 
accomplished  by  adding  a  PRINT  statement  to  the  program. 

10  GET  R$  :   IF  R$  =  ""  THEN  10 
20  PRINT  fl$; 
30  GOTO  10 
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This  simple  program  will  echo  to  the  screen  exactly  what  is  typed  at  the 
keyboard.  Pressing  the  STOP  key  will  stop  the  program. 

The  Keyboard  as  Joystick 

This  section  is  presented  in  "case  study"  form.  Before  discussing  the  program 
listing,  it  will  explain  some  of  the  steps  taken  in  designing  the  program  to  help 
you  understand  both  the  program  listing  and  the  programming  process  itself. 

The  make-believe  joystick  will  act  just  like  the  ones  made  by  Commo- 
dore. You  can  make  it  point  in  various  directions  (left,  right,  up,  down,  and 
diagonally)  by  pressing  different  keys.  It  will  also  have  a  Fire  button, 
although  it  can't  be  pushed  while  a  direction  key  is  being  held  down. 

CHOOSING  THE  KEYS 

First  select  the  keys  that  will  make  up  the  joystick.  Nine  keys  are  needed: 
eight  for  the  various  pointing  directions  and  one  for  the  Fire  button.  The  keys 
should  be  arranged  so  they  are  easy  to  use.  The  following  arrangement  uses 
the  keys  that  are  naturally  under  the  right  hand  when  touch-typing.  Their 
circular  pattern  is  easy  to  learn  and  remember. 


^     0  o 


DESIGNING  THE  INTERFACE 
TO  THE  MAIN  PROGRAM 

Now  let  us  look  at  the  programming  necessary  to  interpret  the  keys  and 
simulate  the  joystick.  The  subroutine  should  be  compatible  with  the  one 
described  for  the  actual  joystick  so  that  you  can  write  programs  that  work 
with  either.  This  subroutine  will  set  the  same  three  variables  for  the  main 
program. 

XI       X  Increment:  controls  movement  to  the  right  or  left 
YI        Y  increment:  controls  movement  up  or  down 
FB       tells  whether  the  Fire  button  was  pressed 
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XI  is  set  to  —  1  for  left,  + 1  for  right,  and  0  for  neither.  YI  is  set  to  —  1  for  down, 
+ 1  for  up,  and  0  for  neither.  If  the  K  key  is  pressed,  FB  will  be  a  1 ;  otherwise,  it 
will  be  a  0 


LOADING  THE  TABLES 

The  program  will  interpret  the  keys  by  looking  them  up  in  a  table.  It  uses 
other  tables  for  the  XI  and  YI  values.  These  tables  will  be  stored  as  arrays  in 
the  program.  The  first  array  (KT$)  contains  the  values  of  the  keys  that  make 
up  the  joystick.  The  other  two  arrays  contain  the  values  of  XI  and  YI  that 
correspond  to  those  keys.  For  example,  KT$(5)  contains  the  letter  U,  which 
means  "up  and  left,"  so  XT(5)  contains  —  1  and  YT(5)  contains  1 .  To  save  time 
when  scanning  the  keyboard,  build  these  tables  in  a  separate  subroutine  that 
is  executed  only  once  at  the  beginning  of  the  program. 

62000  REM  KEV  TRBLE  VALUES 

62100  DATA  I , 0, L, " . " , " , " >  M, J ,U 

62200  REM  X  INCREMENT  VALUES 

62300  DATA  0,1,1,1,0,-1,-1,-1 

62400  REM  V  INCREMENT  VALUES 

62500  DATA  1,1,0,-1,-1,-1,0,1 

62600  FOR  1=0  TO  ?>  READ  KT$U>:  NEXT 

62700  FOR  1=0  TO  ?•  READ  XT<I>:  NEXT 

62800  FOR  1*0  TO        READ  VT(I>:  NEXT 

62850  REM  MAKE  ALL  KEYS  REPEAT 

62900  POKE  650,  128 


Your  program  must  call  this  subroutine  before  attempting  to  use  the  "joy- 
stick" in  order  to  translate  the  keys  correctly. 

When  using  this  routine,  be  careful  where  you  place  the  DATA  state- 
ments. Remember  that  the  READ  statement  starts  with  the  first  DATA 
statement  in  the  program.  If  you  put  additional  DATA  statements  in  this 
program,  you  may  find  it  helpful  to  separate  the  ones  shown  here  from  the 
subroutine  and  group  them  with  your  own  to  keep  them  in  the  right  order. 


THE  KEYBOARD  INTERPRETER 
SUBROUTINE 

The  subroutine  to  read  the  keyboard  and  translate  the  key  has  high 
statement  numbers  to  force  it  to  the  end  of  the  program. 

63000  XI=0:   VI=0:   FB=0 *  LI=0 
63010  GET  KE* 

63020  IF  KE*  =  ■'"  THEN  RETURN 

63030  IF  KE*  =  KT*(LI>  THEN  VI  =  VTCLI):  XI  *  XT(LI>= 
RETURN 

63040  LI  «  LI+l:   IF  LI  <  8  THEN  63030 
63050  IF  KE*  =  "K"  THEN  FB  =  1 
63060  RETURN 
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This  subroutine  has  a  few  tricky  parts,  so  here  is  a  line-by-line  analysis. 

63000  XI,  YI,  and  FB  are  set  to  zero  first.  Since  there  are  three  places 
where  you  RLTuivN,  the  old  valuer  mu^i  oe  eia&cu  ociuie  you 
start. 

63010   checks  to  see  if  any  key  is  pressed. 

63020  if  not,  returns,  leaving  all  variables  set  to  zero. 

63030  these  lines  form  a  loop  to  scan  the  key  table  for  the  key  that  was 
63040   pressed.  A  FOR-NEXT  loop  is  not  used,  since  you  want  to 
RETURN  immediately  if  the  key  is  found.  (Remember  that  you 
must  always  terminate  a  FOR  loop  with  a  NEXT,  and  this  loop 
should  stop  as  soon  as  possible.) 

63050  checks  for  the  Fire  button. 

63060   returns  to  main  program. 


USING  THE  KEYBOARD  JOYSTICK 

Your  program  should  be  entered  ahead  of  statement  62000.  You  can 
SAVE  a  copy  of  these  routines  by  themselves  to  be  used  as  a  base  on  which  to 
build  programs. 

To  see  what  can  be  done  with  the  "keyboard  joystick"  routines,  try  using 
them  with  this  demonstration  program. 

10  G0SUB  62000 

20  A*<0)*M  LEFT":   A$a)  =  "  "  :  A$<2>="RIGHTM 

30  B*C0)  =  "DOWN  "  :  B$a>»"  "  •  B*<2)»"UP 

40  C*<0>""FIRE"  :  C*<  1>-" SFIRE1" 
50  POKE  650,  128 
100  PRINT  "3" 

110  PRINT  ,,a,,ifl$<XI  +  l>iV";B*<VI  +  l>jSPC<5)JC*<FB> 
120  GOSUB  63000 
130  GOTO  110 

62000  REM  KEV  TABLE  VALUES 

62100  DATA  I,0,L,M.,,,",",M,J,U 

62200  REM  X  INCREMENT  VALUES 

62300  DATA  0,1,1,1,0,-1,-1,-1 

62400  REM  V  INCREMENT  VALUES 

62500  DATA  1,1,0,-1,-1,-1,0,1 

62600  FOR  1*0  TO  ?'•  READ  KT$(I>:  NEXT 

62700  FOR  1-0  TO  ? READ  XT<I>=  NEXT 

62800  FOR  1=0  TO  7 :  READ  VTCI) :  NEXT 

63000  XI«0:   VI*0=   FB«0 :  LI=0 

63010  GET  KE* 

63020  IF  KE$  =  ""  THEN  RETURN 

63030  IF  KE$  =  KT*CLI>  THEN  VI  =  VTCLI):   XI  *  XTCLI): 
RETURN 

63040  LI  =  LI+1 :    IF  LI  <  8  THEN  63030 
63050  IF  KE*  -  "K"  THEN  FB  *  1 
63060  RETURN 


 CHAPTER 

Graphics 


In  this  book,  graphics  means  the  display  of  pictures,  rather  than  text,  data,  or 
programs,  on  the  screen.  The  picture  could  be  a  face,  an  architectural 
drawing,  a  geometric  shape,  or  simply  an  arrangement  of  text  characters. 

The  C-128  has  extensive  graphics  capabilities.  Some  of  these,  such  as  the 
built-in  graphics  characters  and  the  C-128's  ability  to  display  text  and  pictures 
in  color,  have  been  mentioned  in  the  preceding  chapters.  This  chapter  will 
cover  these  features  in  more  detail  and  describe  the  C-128's  other  graphics 
features,  including  its  ability  to  use  characters  you  design.  As  these  features 
are  introduced,  you  will  see  programming  techniques  for  producing  colorful 
and  animated  displays. 

The  Video  Interface  Chip 

The  6566  Video  Interface  Chip  (VIC-II  chip),  used  for  both  C-64  and  C-128 
mode  graphics,  is  a  complex  integrated  circuit  that  generates  the  picture  and 
sound  produced  by  the  C-128  on  your  television  or  monitor.  (It's  called  the 
"VIC-II"  because  it's  an  improved  version  of  the  original  VIC  chip  that  was 
used  in  Commodore's  VIC  20.) 
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The  VIC-II  chip  acts  as  a  video  interface:  it  translates  computer  signals 
into  television  signals  that  produce  a  picture  on  the  screen. 

Your  program  communicates  with  the  VIC-II  chip  using  PEEK  and 
POKE.  Much  of  the  art  of  C-128  graphics  involves  knowing  what  to  POKE 
and  where  to  PEEK.  That  is  the  focus  of  this  chapter. 

The  C-128  Screen 

Look  again  at  the  screen,  your  canvas  for  graphics  artistry.  Figure  6-1 
presents  a  blank  screen.  Notice  that  it  is  divided  into  two  areas,  the  border  and 
the  background.  The  border  frames  the  background;  since  television  screens 
do  not  have  straight  edges,  the  border  fills  the  gap  between  the  display  and  the 
edge  of  the  television  screen.  The  background  is  the  working  area  of  the 
screen.  Both  the  text  and  the  graphics  created  by  your  programs  are  displayed 
here.  The  background  consists  of  25  rows  of  40  characters  each,  as  shown  in 
Figure  6-2.  Notice  that  the  rows  are  numbered  from  0  to  24,  and  the  columns 
from  0  to  39.  The  formulas  for  manipulating  screen  data  that  will  be  presented 
throughout  this  chapter  are  much  simpler  if  you  think  of  the  screen  as  starting 


Background 


Border 


FIGURE  6-1.  The  C-128  screen 
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FIGURE  6-2.  The  screen  divided  into  rows  and  columns 


at  row  0,  column  0,  rather  than  at  row  1,  column  1.  All  discussions  and 
examples  in  this  chapter  will  use  this  numbering  convention. 

Border,  Background, 
And  Character  Colors 

The  colors  of  the  border,  the  background,  and  the  individual  characters  can 
be  set  independently.  When  the  C-128  is  powered  ON  (or  reset  with  the 
RUN/ STOP  and  RESTORE  keys),  the  background  is  black  and  the  characters 
and  border  are  green.  You  can  change  these  colors  at  any  time. 

The  background  and  border  colors  are  stored  in  the  VIC-II  chip.  They 
can  be  changed  simply  by  POKEing  a  number  into  a  memory  location  or  by 
using  the  COLOR  command.  The  border  color  is  controlled  by  location 
53280,  while  the  background  color  is  kept  in  location  53281.  A  table  of  the 
POKE  values  for  all  their  possible  values  is  provided  in  Appendix  D.  Here  is  a 
sample  program  in  C-64  mode  that  uses  POKE. 

10  A=l 

20  COLOR  4, A 

30  PRINT  A 

40  BET  A*:    IF  A*=M"  THEN  GOTO  40 
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50  A=A+1 

60   IF  A=17  THEN  END 
70  GOTO  20 

Here  is  the  equivalent  program  in  C-128  mode  that  uses  the  COLOR 
command. 

10  A=0 

20  POKE  53280,  A 
30  PRINT  A 

40  GET  A*:    IF  A*=""  THEN  GOTO  40 
50  A=A+1 

60   IF  A=16  THEN  END 
70  GOTO  20 

The  color  of  each  character  on  the  screen  can  be  set  individually.  Each 
character  has  its  own  location  in  an  area  called  color  memory.  Later,  this 
chapter  will  explain  how  to  access  this  color  memory  directly,  but  you  can 
make  the  C-128  take  care  of  it  for  you.  On  the  front  of  the  numeric  keys  1 
through  8  are  printed  abbreviations  for  the  sixteen  character  colors. 


Upper 

Key 

Abbreviation 

Color 

1 

BLK 

Black 

2 

WHT 

White 

3 

RED 

Red 

4 

CYN 

Cyan 

5 

PUR 

Purple 

6 

GRN 

Green 

7 

BLU 

Blue 

8 

YEL 

Yellow 

To  change  the  color  of  the  characters,  press  and  hold  the  CTRL  key  and  then 
press  the  key  for  the  color  you  desire.  All  characters  generated  at  the  key- 
board or  by  a  program  will  appear  in  the  color  selected.  Only  characters 
displayed  after  you  set  the  new  color  will  be  affected;  those  already  on  the 
screen  will  not  be  changed. 

To  change  to  the  lower  color  marked  on  the  keys,  simply  press  the 
appropriate  key  with  the  Commodore  key. 
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Key 


2 
3 
4 
5 
6 
7 
8 


Lower 
Color 

Orange 
Brown 
Light  Red 
Dark  Gray 
Medium  Gray 
Light  Green 
Light  Blue 
Light  Gray 


Players  and  Playfields 

Many  graphics  programs,  especially  games  and  simulations,  move  one  or 
more  objects  against  a  fixed  background.  To  avoid  confusion  with  other 
terms,  the  objects  will  be  referred  to  as  players,  and  the  background  as  the 
playfield.  The  C-128  offers  a  variety  of  ways  to  build  both  players  and 
playfields. 

Not  all  players  will  move,  and  the  playfield  may  change.  In  fact,  in  some 
applications,  the  players  will  stay  in  one  place  and  the  background  will  move, 
like  in  the  old  movies  where  the  stagecoach  sat  still  while  the  painted  scenery 
rolled  by  behind  it. 


Simple  players  can  be  made  using  the  C-I28's  built-in  graphics  characters. 
These  are  the  shapes  and  symbols  printed  on  the  front  of  the  keys.  For 
example,  the  following  short  program  will  display  a  drawing  of  a  car  on  the 
screen: 

106  PRINT  "IT 

200  PRINT  "  /~"  »» 

300  PRINT  V 

400  PRINT  "I  I  " 

500  PRINT  "  0  0 


GRAPHICS  WITH  THE  EXTENDED 
CHARACTER  SET 
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One  of  the  advantages  of  creating  displays  with  PRINT  statements  is 
that  you  can  doodle  on  the  screen  in  immediate  mode  until  you're  satisfied 
with  your  player,  and  then  build  the  PRINT  statements  around  it.  This  is  how 
the  car  was  built  in  the  sample  program.  Here  is  the  process  step  by  step,  using 
a  simpler  example. 

Step  1:  Clear  the  screen.  Use  the  SHIFT  and  CLR  HOME  keys  (Figure 
6-3a). 

Step  2:  Draw  the  top  half  of  the  diamond.  Type  SHIFT-N  and  then 
SHIFT-M  (Figure  6-36).  Don't  press  RETURN;  if  you  do,  the 
C-128  will  try  to  execute  what  you  just  typed  and  print  a 
READY  message  on  your  picture.  (If  you  type  any  non- 
graphics  characters,  you  may  also  get  a  7SYNTAX  ERROR 
message.)  To  avoid  this,  type  SHIFT-RETURN.  The  cursor  will 
still  move  down  to  the  beginning  of  the  next  line,  but  the  C-128 
will  not  try  to  execute  your  picture. 

Step  3:  Draw  the  bottom  half  of  the  diamond.  Use  SHIFT-RETURN  to 
get  to  the  next  line.  Type  SHIFT-M  and  SHIFT-N  to  complete  the 
diamond  (Figure  6 -3c). 

Step  4:  Home  the  cursor.  Press  the  CLR  HOME  key  without  pressing  the 
SHIFT  key  (Figure  6-3d). 

Step  5:  Insert  four  spaces  with  the  INS/  DEL  key.  This  leaves  room  for  a 
line  number,  a  "?"  for  PRINT,  and  a  double  quote  to  start  a 
string  (Figure  6-3e). 

Step  6:  Type  in  the  PRINT  statement.  Enter  the  line  number  (10),  a 
question  mark,  and  the  double  quote  (Figure  6-3/). 

Step  7:  Press  RETURN.  Don't  use  SHIFT  this  time.  BASIC  stores  the 
first  line  of  the  diamond  as  a  program  line.  Repeat  steps  5 
through  7  for  the  second  line  of  the  drawing,  using  a  line 
number  of  20  this  time. 

You  now  have  a  program  that  can  be  RUN  to  display  the  diamond 
drawing.  This  method  can  be  used  to  reproduce  almost  anything  you  can 
sketch  on  the  screen,  from  a  simple  square  to  a  complex  picture.  The  only 
restriction  is  that  you  can't  completely  fill  the  screen,  since  you  will  need  room 
to  insert  the  PRINT  statements. 

Now  experiment  a  bit  with  some  of  your  own  designs.  For  the  moment, 
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FIGURE  6-3.  Drawing  a  diamond 
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stay  away  from  reversed  characters.  They  require  some  special  handling  that 
will  be  covered  in  the  next  section. 

Using  Reversed  Characters 

You  may  have  already  notice  that  reversed  characters  have  a  special  use  in 
PRINT  statements:  they  represent  keys  that  do  not  generate  "normal" 
characters  —  such  as  HOME,  the  cursor  controls,  and  the  color  keys.  If  you 
enter  a  reversed  character  directly  into  a  PRINT  statement,  one  of  the 
following  will  happen: 

•  The  character  will  be  interpreted  as  a  "special  key"  to  move  the  cursor, 
change  the  color,  and  so  on. 

•  The  character  will  not  match  any  of  the  special  keys:  it  will  be  stored 
as  a  nonreversed  character  when  you  press  RETURN.  This  will  happen 
even  if  the  character  appears  between  quotes  in  the  program. 

To  PRINT  a  single  reversed  character  within  a  string,  enter  a  RVS  ON 
(CTRL-9)  before  the  reversed  character.  The  character  itself  must  appear  in  the 
PRINT  statement  as  a  "normal"  (nonreversed)  character.  If  you  are  building 
PRINT  statements  from  a  screen  sketch,  you  can  insert  the  RVS  ON  using  the 
INS  key.  Remember  that  pressing  the  INS  key  puts  you  in  quote  mode  for  one 
character,  so  the  RVS  ON  will  be  stored  as  part  of  the  PRINT  statement  instead 
of  being  executed. 

The  "reverse  on"  is  reset  automatically  at  the  end  of  the  PRINT  line. 
(Remember  that  a  PRINT  line  can  span  more  than  one  line  on  the  screen.  A 
RETURN  indicates  the  end  of  a  PRINT  line.  If  a  PRINT  statement  ends  with  a 
semicolon,  BASIC  does  not  add  a  carriage  return,  and  characters  will  still  be 
displayed  in  reverse.)  If  normal  characters  follow  the  reversed  ones  on  the 
PRINT  line,  insert  a  RVS  OFF(CTRL-O)  before  the  first  nonreversed  character. 

To  illustrate  the  problem  and  solution,  you  can  modify  the  Diamond 
program  to  produce  a  solid  block  instead  of  an  outline.  Follow  the  steps 
displayed  in  Figure  6-3,  but  use  different  characters  to  make  up  the  player. 

•  In  step  2,  after  clearing  the  screen,  press  the  RVS  ON  key  (CTRL-9), 
SHlFT-£,  and  press  the  C-  . 

•  In  step  3,  press  the  C-  and  SHiFT-£. 

When  you  list  the  program,  you  will  notice  that  the  first  SHJFT-£  has 
changed  to  normal,  but  the  C1  has  not. 
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10  PRINT  "PV 
28  PRINT 

Now  run  the  program,  and  observe  the  effect  of  the  reversed  C-  .  The 
second  line  has  turned  cyan. 

To  change  the  program  so  it  displays  what  was  originally  wanted,  follow 
these  steps:  List  the  program  to  display  it  on  the  screen.  Position  the  cursor 
over  the  SHlFT-£  in  line  10  and  press  SHIFT-INS.  This  inserts  a  space  and 
temporarily  puts  the  C-128  in  quote  mode.  Press  CTRL-9  (RVS  ON).  Since  it  is 
in  quote  mode,  the  C-128  will  insert  the  RVS  ON  in  the  PRINT  statement 
(displayed  as  a  reversed  "R")  instead  of  switching  to  reversed  characters. 
When  the  PRINT  statement  is  executed,  the  reversed  R  will  be  recognized 
and  the  C-128  will  start  displaying  reversed  characters.  Change  the  reversed 
Cs  to  a  normal  one  so  that  it  won't  turn  the  screen  cyan  again.  Move  the 
cursor  over  and  type  a  C-  over  the  old  one. 

The  program  should  now  look  like  this: 

10  PRINT  "STr 
20  PRINT  HT" 

Run  the  program  again,  and  you  will  see  that  the  diamond  is  now 
correctly  displayed. 

Adding  Color  to  Your  Display 

Like  reversed  characters,  color  displays  require  special  care.  The  problem 
here  is  somewhat  different:  the  C-128  simply  forgets  the  color  of  a  character 
once  it's  off  the  screen.  This  happens  because  the  color  is  not  actually  part  of 
the  character.  As  mentioned  earlier,  there  is  an  area  in  memory  set  aside  to 
hold  the  colors  of  the  characters  on  the  screen.  When  you  list  your  program, 
the  C-128  sets  the  color  for  each  character  to  the  active  character  color.  When 
first  powered  ON,  it  uses  green  for  the  character  color.  In  Chapter  2  you 
learned  how  to  change  the  color  from  the  keyboard  by  using  the  CTRL  key.  As 
you  are  about  to  see,  your  program  can  also  change  it.  Once  a  character  is 
gone  from  the  screen,  the  color  memory  is  reused  to  show  the  color  of  the 
character  that  takes  its  place.  Only  the  character  itself  is  stored  as  part  of  the 
program. 

As  with  reversed  characters,  this  problem  is  solved  by  inserting  control 
characters  into  the  program  to  set  the  color.  For  example,  to  make  the 
diamond  red  instead  of  blue,  insert  a  CTRL-3  into  line  10  following  the  "reverse 
on"  (reversed  R)  so  that  the  line  looks  like  the  following. 
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10  print  "awrr 
20  print 

Now  run  the  program.  Notice  that  the  entire  diamond  is  red,  not  just  the 
first  line.  Color  controls,  unlike  the  "reverse  on"  control,  are  not  reset  when 
you  start  a  new  line.  They  remain  in  effect  until  a  new  color  is  set  or  until  you 
reset  the  C-128  with  the  RUN/ STOP  and  RESTORE  keys. 

CREATING  DISPLAYS  WITH  POKE 

Sometimes  it  is  not  practical  to  use  PRINT  to  build  a  graphics  display.  For 
example,  if  several  players  are  moving  about  on  the  screen,  you  may  need  to 
detect  when  they  collide  with  each  other  or  with  an  object  on  the  playfield.  Or 
you  might  want  to  have  a  cursor  on  the  screen  when  reading  characters  with 
GET.  For  applications  like  these,  you  will  want  to  access  the  display  directly. 
The  C-128  allows  you  to  do  this  using  PEEK  and  POKE. 

Screen  Memory 

The  characters  displayed  on  the  screen  are  stored  in  the  C-128's  memory.  The 
VIC-II  chip  reads  the  image  of  a  character  from  memory  as  it  is  being 
displayed  on  the  screen.  The  characters  are  stored  in  an  area  called  screen 
memory,  and  the  colors  of  the  characters  are  stored  in  color  memory.  Because 
these  areas  are  part  of  the  C-128's  memory,  you  can  use  PEEK  and  POKE  to 
examine  and  change  the  contents  of  the  display. 

FINDING  SCREEN  MEMORY 

In  most  computers,  the  location  of  screen  memory  is  part  of  the  hard- 
ware design  and  cannot  be  changed.  In  the  C-128,  although  the  number  of 
rows  and  columns  in  screen  memory  is  fixed,  its  starting  point  is  not.  The 
VIC-II  chip  uses  one  of  its  internal  registers  to  keep  track  of  the  start  of  the 
screen  memory,  and  this  pointer  can  be  changed.  Some  of  the  programs  that 
you  will  see  later  in  this  chapter  will  make  use  of  this  capacity.  Programs  that 
PEEK  and  POKE  directly  into  screen  memory  must  be  aware  of  where  the 
screen  is.  This  is  easily  done.  There  is  a  different  memory  location  used  by 
BASIC  that  tells  the  C-128  where  the  screen  begins.  If  you  PEEK  this  memory 
(location  648  in  C-64  mode  and  2604  in  C-128  mode)  and  run  one  of  the 
following  routines,  you  will  get  the  starting  address  of  screen  memory.  For 
C-64  mode,  use 

10  SB»256*PEEK<648) 
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For  C-128  mode,  the  screen  is  controlled  by  memory  location  2604.  The 
sample  programs  will  keep  these  memory  locations  up-to-date  when  they 
move  screen  memory.  If  you  follow  this  convention  in  your  programs,  you  can 
write  programs  that  work  no  matter  where  the  screen  memory  is  located. 

SCREEN  MEMORY  LAYOUT 

The  characters  you  see  on  the  screen  are  stored  in  memory  as  an  array  of 
25  rows  and  40  columns.  This  array  is  not  a  BASIC  variable.  It  is  simply  a 
1000-byte  area  in  the  C-128's  memory  that  you  can  access  with  PEEK  and 
POKE,  but  you  will  find  it  helpful  to  visualize  this  area  as  an  array.  Each 
element  of  this  array  holds  one  character  from  the  screen.  Element  (0,0) 
contains  the  character  in  the  upper-left  corner  of  the  display,  and  element 
(24,39)  holds  the  character  in  the  lower-right  corner. 

Once  you  have  found  where  screen  memory  starts  by  using  the  formula 
from  the  preceding  section,  you  can  readily  calculate  where  to  POKE  for  a 
particular  character.  The  formula  is 

POKE  location  =  start  of  screen  +  column  +  40  *  row 

In  order  to  use  this  formula,  you  must  number  screen  columns  from  0  to  39, 
and  rows  from  0  to  24.  As  an  example  of  this  formula,  type  in  the  following 
C-64  mode  program: 

100  SB-256IHPEEKC648) 

110  REM  FILL  SCREEN  MEMORV  WITH  "d" 
120  FOR  I»0  TO  999 
130  POKE  SB+1,0 
140  NEXT  I 

150  REM  WRIT  FOR  A  KEV  TO  BE  PRESSED 
160  GET  X* 

170  IF  X$=,M"  THEN  160 

180  REM  CHANGE  BACKGROUND  TO  BLACK 

190  POKE  53281,0 

To  try  this  routine  in  C-128  mode,  replace  line  100  with  SB=1024. 

Color  Memory 

Earlier  in  this  chapter  it  was  mentioned  that  the  colors  of  the  characters  on 
the  screen  are  kept  in  a  special  area  called  color  memory.  An  understanding  of 
how  to  use  color  memory  is  essential  when  POKE  is  used  in  displays,  so 
before  you  proceed  further  with  POKEing  screen  memory,  take  a  look  at 
color  memory. 
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FINDING  COLOR  MEMORY 

Unlike  screen  memory,  color  memory  never  moves;  in  40-column  mode, 
it  is  always  in  locations  55296  through  56295.  As  with  screen  memory,  there  is 
one  location  in  color  memory  for  each  character  on  the  screen.  The  order  of 
character  colors  is  the  same  as  that  of  the  characters  themselves,  so  the 
formula  used  to  find  a  character's  location  in  color  memory  is  like  the  one 
used  to  locate  the  character  in  screen  memory. 

Color  memory  location  =  55296  +  column  +  40  *  row 
CONTENTS  OF  COLOR  MEMORY 

The  color  of  each  character  is  stored  in  color  memory  as  a  number  from 
0  to  15.  The  colors  produced  by  these  numbers  are  as  follows: 


0 

Black 

8 

Orange 

1 

White 

9 

Brown 

2 

Red 

10 

Light  Red 

3 

Cyan 

11 

Dark  Gray 

4 

Purple 

12 

Medium  Gray 

5 

Green 

13 

Light  Green 

6 

Blue 

14 

Light  Blue 

7 

Yellow 

15 

Light  Gray 

Unlike  other  areas  of  C-128  memory,  color  memory  uses  only  four  bits 
per  location.  Only  four  bits  are  needed  to  hold  the  color  number  (0  to  15). 
Since  the  upper  four  bits  are  not  used,  Commodore  did  not  include  a  memory 
chip  to  hold  them.  If  you  POKE  a  number  larger  than  15  into  a  color  memory 
location,  the  part  of  it  held  in  those  "missing"  bits  will  be  lost,  as  shown  here. 


10101010 

A  binary  value  of 204;  when  the  upper  4  bits  are  dropped, 

1010 

the  number  stored  is  a  12. 

11111111 

255 

1111 

becomes  a  15. 

00000111 

A  value  of  7,  however, 

0111 

is  not  changed. 

Since  there  is  no  memory  chip  to  supply  the  upper  four  bits  when  color 
memory  locations  are  read,  they  will  take  on  unpredictable  values.  Remember 
that  a  bit  must  be  either  a  1  or  a  0;  even  if  there  is  no  signal  present  on  a  chip's 
input  pin,  the  chip  must  assign  it  some  value.  With  no  signal  coming  into  the 
pins  for  the  upper  four  bits,  the  chip  arbitrarily  gives  them  either  a  1  or  a  0 
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value.  When  PEEKing  color  memory,  always  discard  the  nonexistent  bits. 
This  can  be  done  by  using  AND  to  mask  them,  as  described  in  Chapter  5. 

10  BV*PEEK< 55400)  AND  15 


Screen  Display  Codes 

Once  you  understand  where  to  POKE  to  change  the  display,  you  will  need  to 
know  what  value  to  put  there.  Commodore  computers,  including  the  C-128, 
do  not  use  the  same  character  code  in  screen  memory  that  they  use  in 
programs.  Most  computers  store  characters  in  a  standard  code  called  ASCII 
(American  Standard  Code  for  Information  Interchange).  Commodore  com- 
puters use  an  "extended"  ASCII  for  all  purposes  other  than  representing 
characters  in  screen  memory.  The  "extensions"  are  graphics  characters  and 
certain  control  codes  not  used  by  other  manufacturers.  Many  of  the  control 
codes  do  not  have  a  displayable  character  associated  with  them.  In  order  to 
make  as  many  graphics  codes  as  possible  available  on  the  screen,  Commodore 
devised  a  different  code  for  screen  memory.  This  code  eliminates  some  ASCII 
characters  and  changes  the  values  of  others. 

Appendix  D  contains  a  table  showing  the  screen  display  codes.  If  your 
program  is  POKEing  characters  that  are  set  at  the  time  you  write  it,  you  can 
simply  look  them  up  in  the  table.  If  you  do  not  know  in  advance  what 
characters  you  will  be  POKEing,  your  program  must  convert  them  from 
ASCII  to  screen  display  code.  This  might  be  necessary  if,  for  example,  your 
program  uses  GET  to  read  instructions  from  the  keyboard,  and  you  want  to 
echo  the  characters  in  a  particular  place  on  the  display. 

The  conversion  to  screen  code  can  be  done  with  little  effort,  because  the 
ASCII  codes  that  were  changed  were  moved  in  blocks  of  32  characters.  The 
changes  are  shown  in  Table  6-1. 

Here  is  a  simple  subroutine  that  takes  a  key  value,  KV$,  and  converts  it 
to  a  screen  code,  SC.  If  the  key  cannot  be  translated  (a  cursor  control  key,  for 
example),  it  returns  a  value  of  —  1.  The  main  program  can  thereby  tell  the 
difference  between  a  displayable  and  a  nondisplayable  keystroke. 

60000  SC-flSC<KV*> 

60010  IF  SCX32  THEN  SO-1    : RETURN 
60020  IF  SC<64  THEN  RETURN 
60030  IF  SCX96  THEN  SOSC-64 1 RETURN 
60040  IF  SCO 28  THEN  SC=S032 :  RETURN 
60050  IF  SCO 60  THEN  SO  128  RETURN 
60060  IF  SCa 92  THEN  SC«SC-64 : RETURN 
60070  IF  SC-C255  THEN  SC«SC- 1 28  :  RETURN 
60060  SC= 126: RETURN 
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TABLE  6-1.  ASCII  to  Screen  Code  Conversion 


ASCII  Code 

Screen  Code 

0-3 1 

None 

Same 

64-95 

0-31 

96-127 

64-95 

128-159 

None 

160-191 

96-127 

192-254 

64-126 

255 

94 

The  Moving  Dot  Revisited 

Chapter  5  presented  a  program  that  moved  a  dot  around  the  screen  as  an 
example  of  using  the  joystick.  For  comparison,  here  is  how  that  program 
could  be  written  using  POKE  instead  of  PRINT.  As  before,  this  program  is 
not  complete;  you  must  add  the  appropriate  subroutine  to  use  either  the 
keyboard  or  the  joystick  for  control.  Here  is  the  program  for  C-64  mode. 


100  REM  CLEAR  SCREEN 

110  PR  I  NT"  IH 11 

120  REM  SET  COLOR  MEMORV 

130  FOR  1*55296  TO  56295 

140  POKE  1,14 

150  NEXT  I 

160  XP«0:VP«0 

170  SB*PEEK<648)*256 

190  REM  MR IN  LOOP 

190  GOSUB  63000 

200  IF  <XI«0>flND<VI»0)flND<FB*0)THEN  190 

210  REM  ERASE  OLD  DOT 

220  POKE  SB+XP+40*VPi32 

230  REM  CALCULATE  NEW  X  POST I ON 

240  XP*XP+XI 

250  IF  XP>39  THEN  XP«0 

260  IF  XP<0  THEN  XP«39 

270  REM  CALCULATE  NEW  V  POST I ON 

280  VPaVP+VI 

290  IF  VP>24  THEN  VP«0 

300  IF  VP<0  THEN  VP*24 

310  REM  POKE  NEW  DOT 

320  POKE  SB+XP+40#VPiBl 

330  GOTO  190 


GRAPHICS  179 


Here  is  the  program  for  C-128  mode. 

110  REM  CLEAR  SCREEN 
120  PRINT  CHR*(147) 
130  XP=0: YP=0 
140  REM  MAIN  LOOP 
150  GOSUB  63000 

160   IF    ( X 1=0) AND (YI=0) AND (FB=0) THEN  150 

170  REM  ERASE  OLD  DOT 

180  POKE  SB+XP+40*YP,32 

190  REM  CALCULATE  NEW  X  POSITION 

200  XP=XP+XI 

210  IF  XP>39  THEN  XP=0 

220  IF  XP<0  THEN  XP=39 

230  REM  CALCULATE  NEW  Y  POSITION 

240  YP=YP+1 

250  IF  YP>24  THEN  YP=0 
260  IF  YP<0  THEN  YP=24 
270  REM  POKE  NEW  DOT 
280  POKE  SB+XP+40*YP,  81 
290  GOTO  150 


ANIMATING  YOUR  PLAYERS 


There  are  two  facets  to  player  animation.  The  first  has  already  been  dis- 
cussed: moving  a  player  around  on  the  screen.  The  second  involves  changing 
the  player  itself,  so  that  it  appears  to  be  doing  something.  To  animate  a  player, 
one  or  more  of  the  characters  that  make  it  up  are  changed,  giving  the  illusion 
that  it  is  moving.  For  example,  this  program  produces  a  windshield,  with 
wipers  that  sweep  back  and  forth. 


10  DLV* 150 

20  REM  BUILD  WINDSHIELD 

30  PR  I  NT  "H,  s" 

40  PRINT"  I  I" 

50  PRINT"   

60  REM  SWEEP  WIPERS  TO  RIGHT 
70  FOR  1*1  TO  4 
80  ON  I  GOSUB  180,240,300,360 
90  FOR  J-l  TO  DLV  :  NEXT 
100  NEXT 

110  REM  SWEEP  WIPERS  TO  LEFT 

120  FOR  1-3  TO  2  STEP  -1 

130  ON  I  GOSUB  180,240,300,360 

140  FOR  J-l  TO  DLV  :  NEXT 

130  NEXT 

160  GOTO  70 

170  REM  SHOW  WIPERS  RT  10  O'CLOCK 
180  POKE  1065,77 
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190  POKE  1066,32 
200  POKE  1Q6?,?? 
210  POKE  1068,32 
220  RETURN 

230  REM  SHOW  WIPERS  RT  12  0' CLOCK 

240  POKE  1065,32 

250  POKE  1066,101 

260  POKE  1067,32 

270  POKE  1068,101 

280  RETURN 

290  REM  SHOW  WIPERS  RT  2  0/ CLOCK 

300  POKE  1065,32 

310  POKE  1066,78 

320  POKE  1067,32 

330  POKE  1068,78 

340  RETURN 

350  REM  SHOW  WIPERS  RT  3  O'CLOCK 
360  POKE  1066,100 
370  POKE  1068,100 
380  RETURN 


The  program  has  several  major  parts,  which  will  be  examined  in  detail. 
Lines  30  through  50  clear  the  screen  and  display  the  windshield  using  PRINT 
statements. 

Lines  70  through  100  sweep  the  wipers  from  left  to  right.  They  are  then 
swept  back  to  the  left  by  lines  120-150.  These  loops  change  the  display  by 
calling,  in  turn,  subroutines  that  put  the  wipers  in  particular  positions  by 
POKEing  characters  to  the  screen.  Each  subroutine  erases  the  wipers  from 
the  screen  and  puts  them  in  a  new  position. 

Two  of  the  most  important  lines  in  the  program  are  lines  90  and  140. 
These  FOR-NEXT  loops  slow  down  the  program.  Without  such  delay  loops, 
the  display  would  change  too  quickly,  reducing  the  movement  to  a  blur. 
Choosing  the  lengths  of  the  delay  loops  is  crucial  to  animation.  This  is 
especially  true  of  programs  that  produce  complex  movements.  When  devel- 
oping such  programs,  you  can  expect  to  spend  much  of  your  time  fine-tuning 
the  delays  to  create  a  display  that  moves  smoothly  at  the  speed  you  want.  Try 
experimenting  with  the  sample  program:  the  length  of  the  delay  loops  is 
controlled  by  the  variable  DLY  and  the  value  of  this  variable  is  set  in  line  10.  A 
lower  value  shortens  the  delay  loops,  making  the  display  change  more 
quickly.  Increasing  the  value  lengthens  the  delay  loops,  slowing  the  move- 
ment of  the  wipers. 

It  is  difficult  to  do  complex  animation  with  the  built-in  character  set 
unless  you  are  working  with  a  very  large  player.  In  most  cases,  you  must  move 
part  of  your  player  an  entire  character  space  to  move  it  at  all.  This  makes  the 
motion  somewhat  jerky  unless  the  player  takes  up  a  large  portion  of  the 
screen.  To  produce  more  subtle  movements  with  small  players,  you  must 
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design  your  own  characters.  Techniques  for  making  and  using  your  own 
characters  will  be  discussed  later  in  this  chapter. 

Combining  PR  IN  Ted  and  POKEd  Graphics 

As  you  have  seen,  both  the  PRINT  and  POKE  methods  have  strengths  and 
weaknesses  in  building  graphics  displays.  For  those  programs  that  have 
players  moving  against  a  fixed  background,  a  combination  of  PRINT  and 
POKE  often  works  best.  Using  PRINT  statements  to  display  graphics  on  the 
screen  in  combination  with  POKEs  that  jump  to  any  location  on  the  screen 
can  make  the  development  of  a  program  much  easier. 

Racetrack  Game 

Figure  6-4  is  a  listing  of  a  simple  game  called  Racetrack,  an  adaptation  of  a 
common  pencil-and-paper  game.  This  program  demonstrates  some  of  the 
techniques  discussed  so  far  in  this  chapter.  (To  run  this  program  in  C-128 
mode,  replace  line  45100  with  the  C-128  screen  location  line.) 


100  GOSIJE  40008 

200  CR-15 

300  C02 

356  POKE  53275,254 

400  POKE  SB+CC+CR*40,0 

1000  IF  XSO0  AND  TI>XT  THEN  CC"CC+SGN(XS> 

XT»TI+60/FlBS<X8> 

1100  IF  VSO0  FIND  TI>VT  THEN  CR-CR+SON<VS> 

:VT-TI+S0/'flBS<VS) 

1200  IF  C(X0  OR  CC>39  THEN  4000 

1300  IF  CR<0  OR  CR>24  THEN  4000 

1400  POKE  Efl,32 

1500  BR=SB+CC+CR*40 

1600  TG-PEEKCBFD 

1700  IF  TGO0  AND  TQ032  THEN  5500 

1600  POKE  Bfl,0 

1900  IF  TT>TI  THEN  1000 

2000  TT=TI+30 

2100  POKE  V2j129 

2200  GOSUB  63000 

2300  POKE  V2,0 

2400  XS*XS+XI   :  VS=VS+VI 

2500  GOTO  1000 

4000  IF  CC<0  THEN  CC=0 

FIGURE  6-4.  Racetrack  program 
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4100  IF  CC>39  THEN  CC=39 

4200  IF  CR<0  THEN  CR«0 

4300  IF  CR>24  THEN  CR=24 

4400  BA*SB+CC+CR*40 

5000  POKE  BA,0 

5100  FOR  1=1  TO  350  :  NEXT  I 

5200  POKE  BA,32 

5300  FOR  1*1  TO  350  :  NEXT  I 

5400  GET  fl*:   IF  AtO""  THEN  100 

5500  GOTO  5000 

40000  PRINT'TJ"; 

40100  SB*  1024 

40200  FOR  1*55296  TO  56295 : POKE  I, 14: NEXT 
40300  XS»0   :   VS=0  :   XT*0  ••  VT=0 
40400  REM  JOYSTICK  VARIABLES 
40500  JS=56321 

40600  UM5i=l   :  DMJi-2  :  LMX*4  :  RMJi«8 
40700  REM  SET  UP  SOUND 
40800  V2*54283 
40900  POKE  V2+l,80 
41000  POKE  54295-0 
41100  POKE  54296,15 
41200  PRINT"! 
41300  PRINT"!* 
41400  PRINT"! 
41500  PRINT" 
41600  PRINT" 
41700  PRINT" 
41800  PRINT" 
41900  PRINT" 
42000  PRINT" 
42100  PRINT" 
42200  PRINT" 
42300  PRINT" 
42400  PRINT" 
42500  PRINT" 
42600  PRINT" 
42700  PRINT" 
42800  PRINT" 
42900  PRINT" 
43000  PRINT" 
43100  PRINT" 
43200  RETURN 
63000  SS»PEEK(JS> 

63010  XI*SGN<SS>:  AND  LMJO-SGNCSSZ  AND  RMJi) 
63020  VI»SON<SSX  AND  UMJi>-SON<SSfi  AND  DMJO 
63030  RETURN 


FIGURE  6-4.  Racetrack  program  (continued) 
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The  pencil-and-paper  version  of  Racetrack  is  played  on  a  sheet  of  graph 
paper  with  the  course  drawn  on  it.  Here  is  a  typical  course. 


The  C-128  version  of  the  game  uses  one  character  location  on  the  screen 
for  each  square  on  the  graph  paper. 
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The  rules  of  the  game  are  quite  simple. 

1 .  The  car  moves  in  both  the  horizontal  and  vertical  dimensions  at  a 
speed  of  a  certain  number  of  squares  per  second.  It  can  move  in  both 
dimensions  at  once.  For  example,  to  travel  diagonally  it  can  move  at  a 
rate  of  one  square  up  and  one  square  right  per  second. 

2.  On  each  turn  (about  twice  a  second),  the  player  can  speed  up  or  slow 
down  by  a  rate  of  one  square  per  second  in  each  dimension.  For 
example,  if  a  player  is  moving  at  a  rate  of  3  squares  up  and  l  right,  he 
or  she  can  change  his  or  her  speed  to  4  up,  l  right;  2  up,  l  right;  2  up,  2 
right;  2  up,  0  right,  and  so  on. 

3.  If  the  car  goes  off  the  track,  it  crashes  and  the  game  is  over. 

The  Racetrack  program  listed  in  Figure  6-4  is  a  somewhat  crude  version 
of  the  game,  but  it  does  provide  some  practical  examples  of  techniques  you 
can  use  in  writing  graphics  and  animation  programs.  It  uses  PRINT  to 
display  a  playfield  that  was  originally  developed  as  a  screen  sketch.  It  also 
contains  some  examples  of  using  POKE  to  move  the  player  and  using  PEEK 
to  detect  collisions.  To  start  your  examination  of  the  program,  here  are  the 
main  variables. 

Variable 

Name  Description 

CC  Car  Column  —  the  column  number  on  the  screen  where  the 

car  is  to  be  displayed. 

CR  Car  Row  —  the  screen  row  where  the  car  is  located. 

TT  Test  Time —  the  value  that  TI  will  have  when  it  is  time  to 

test  the  joystick  for  the  next  turn. 

XS  X  Speed — the  car's  speed  in  the  X  dimension:  negative  is 

toward  the  left,  positive  toward  the  right. 

XT  X  Time  —  the  value  of  TI  when  it  is  time  to  move  in 

the  X  dimension. 

YS  Y  Speed — the  car's  speed  in  the  Y  dimension:  negative  is 

up,  positive  is  down. 

YT  Y  Time  —  the  value  of  TI  when  it  is  time  to  move  in 

the  Y  dimension. 

Lines  1000  through  2500  make  up  the  main  processing  loop  of  the 
program.  The  program  runs  continuously  through  the  code,  looking  for 
something  to  do.  On  each  pass,  it  checks  the  current  time  to  see  if  it  should 
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move  the  car  (lines  1000  and  1100)  or  look  at  the  joystick  (line  1600).  If  any  of 
these  things  needs  to  be  done,  the  timer  value  for  the  next  occasion  is  also  set. 

In  lines  1200  and  1300,  the  program  checks  to  ensure  that  the  car  has  not 
gone  off  the  screen.  Lines  1500  and  1600  make  sure  that  the  car  is  not  about  to 
collide  with  a  wall.  If  either  of  these  is  true,  the  program  goes  to  the  "crash" 
routine  at  line  4000. 

Lines  2100  and  2300  sound  a  "tock"  each  time  the  program  tests  the 
joystick.  (The  C-128's  sound  capabilities  are  discussed  in  Chapter  7.) 

The  "crash"  routine  (lines  4000  through  5500)  brings  the  car  back  onto 
the  screen  if  it  has  gone  off  (lines  4000-4400)  and  makes  it  flash  at  a  rate  of 
about  once  per  second  (lines  5000-5300).  As  soon  as  the  user  presses  any  key, 
line  5400  starts  the  game  over. 

Racetrack  is  both  an  example  of  graphics  techniques  and  a  basis  for  your 
own  experiments.  You  might  want  to  try  putting  a  readout  of  the  number  of 
turns  or  seconds  used  in  the  infield,  modifying  the  course,  or  making  sure  that 
the  car  has  really  gone  all  the  way  around  the  course  instead  of  doubling  back 
to  the  finish  line. 


MEMORY  "SEGMENTS" 

The  graphics  features  examined  so  far  have  used  the  screen  memory  area  in 
locations  1024-2023.  However,  the  more  advanced  features  that  will  be  dis- 
cussed access  other  memory  locations  as  well. 

One  of  the  characteristics  of  the  VIC-II  chip  is  that  it  can  only  access  16K 
(16,384  bytes)  of  memory.  Since  the  C-128  has  128K  of  memory,  it  would  seem 
that  most  of  it  can't  be  used  by  the  VIC-II. 

To  circumvent  this  problem,  the  engineers  at  Commodore  divided  the 
C-128's  64K  of  memory  into  eight  "segments,"  each  16K  long.  They  also 
designed  the  C-128  so  that  your  program  can  select  which  of  these  eight 
segments  the  VIC-II  will  use. 

Because  most  of  the  first  segment  (the  one  selected  by  the  C-128  when  it 
is  powered  on)  is  used  by  BASIC,  the  program  examples  will  be  switching  the 
VIC-II  to  other  segments. 

However,  there  are  two  important  points  about  memory  segments  you 
need  to  understand  before  continuing  with  the  rest  of  this  chapter.  The  first  is 
that  all  the  memory  areas  used  by  the  VIC-II  (screen  memory  and  the  new 
ones  youll  learn  about)  must  be  in  the  same  16K  segment. 

The  second  item  to  remember  is  that  pressing  RUN/  STOP-RESTORE  does 
not  always  completely  reset  memory.  Location  648,  as  mentioned  earlier, 
controls  the  screen  location,  and  RUN/  STOP-RESTORE  does  not  restore  it  to  its 


186     C-*28  USER  GUIDE 


"power  on"  value.  If  something  goes  wrong  while  you  are  running  one  of  the 
sample  programs  that  moves  screen  memory  in  C-64  mode,  it  is  possible  for 
BASIC  to  get  confused  about  where  screen  memory  is.  If  this  happens,  the 
screen  editor  won't  work  and  the  computer  won't  be  properly  reset  by 
pressing  RUN  STOP-RESTORE. 

This  sort  of  confusion  will  almost  never  happen,  but  any  program  that 
does  a  lot  of  POKEing  into  memory  can  cause  it  by  changing  the  wrong 
location  in  memory.  Before  RUNning  any  of  the  sample  programs  or  any 
program  that  does  many  POKEs,  be  sure  you  SAVE  a  copy  of  it:  the  typing 
fingers  you  save  may  be  your  own! 

Location  2604,  which  controls  the  screen  location  in  C-128  mode,  is  reset 
if  you  press  RUN/ STOP-RESTORE,  so  in  C-128  mode  you  won't  need  to  take 
these  precautions. 

CUSTOM  CHARACTER  SETS 

The  C-128  can  easily  change  the  shapes  of  the  characters  that  appear  on  the 
screen.  Most  personal  computers  require  hardware  changes  to  use  a  different 
set  of  characters,  but  the  C-128  allows  you  to  create  your  own  characters,  then 
switch  over  to  your  character  set  with  a  simple  POKE.  In  this  section  you  will 
see  how  the  character  set  is  defined  and  how  to  design  your  own  characters 
and  make  them  appear  on  the  screen. 

How  Characters  Are  Displayed 

First,  here  is  a  brief  look  at  how  television  works.  If  you  look  closely  at  your 
television  screen,  youll  notice  that  the  picture  is  made  up  of  individual  dots 
arranged  in  rows.  There  are  about  500  dots  on  each  row  and  about  500  rows 
on  the  screen.  Inside  the  picture  tube,  a  beam  of  electrons  sweeps  back  and 
forth,  one  row  at  a  time,  lighting  up  each  dot  as  it  passes.  The  incoming  TV 
signal  determines  the  brightness  and  color  of  each  dot.  Although  the  process 
of  generating  and  receiving  a  TV  signal  involves  much  more,  all  you  need  to 
know  is  that  the  television  picture  is  made  up  of  rows  of  dots.  The  VIC-II  chip 
generates  the  TV  signals. 

Character  Memory 

This  discussion  of  the  way  a  television  works  leads  to  the  question  of  how  the 
VIC-II  chip  knows  which  dots  to  turn  on.  You  will  recall  that  the  characters 
displayed  on  the  screen  are  stored  in  the  screen  memory  area.  As  it  "paints" 
the  screen,  the  VIC-II  chip  steps  through  screen  memory,  picking  up  the 
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characters  one  at  a  time.  To  determine  which  dots  to  turn  on  for  a  particular 
character,  it  looks  at  a  table  in  memory  that  contains  the  character  shapes. 
This  table  was  worked  out  by  Commodore  and  stored  in  a  special  memory 
chip  in  the  C-128.  This  chip,  called  a  ROM  (Read-Only  Memory),  retains  the 
information  that  was  stored  in  it  at  the  factory,  even  when  power  is  turned 
OFF.  The  area  occupied  by  this  table  is  called  character  memory.  With  a 
POKE,  your  program  can  tell  the  VIC-II  chip  to  use  a  different  area  for 
character  memory  —  one  that  you  can  fill  with  your  own  table.  Finally,  the 
VIC-II  chip  must  know  what  color  to  make  the  character.  This  information 
comes  from  color  memory.  We've  already  examined  the  screen  and  color 
memory  areas,  so  well  look  at  character  memory  and  then  discuss  how  to  use 
these  areas  to  create  displays. 

FORMAT  OF  CHARACTER  MEMORY 

Each  character  on  the  screen  is  made  up  of  a  matrix  that  is  eight  dots 
wide  and  eight  high.  A  magnified  view  of  the  letter  A,  for  example,  would 
look  like  this: 


The  8X8  format  was  chosen  because  each  row  of  the  character  conven- 
iently fits  into  one  byte  of  memory,  and  the  eight  rows  make  a  nice  round 
number  in  the  computer's  binary  number  system.  This  format  also  greatly 
simplifies  custom  character  design.  You  can  lay  out  your  character  on  an 
ordinary  sheet  of  graph  paper  and  convert  each  row  to  its  value  and  location 
in  character  memory. 

The  eight  bytes  that  make  up  the  rows  of  a  character  are  stored  next  to 
each  other  in  character  memory,  with  the  top  row  first.  Each  dot  on  a  row 
corresponds  to  one  bit,  with  the  bit  for  the  leftmost  dot  having  the  highest 
binary  value,  128.  A  bit  value  of  1  means  the  dot  is  "on"  (displayed  in  the 
character  color).  A  value  of  0  means  the  dot  is  "off"  (displayed  in  the  screen 
color).  In  character  memory,  the  letter  A  looks  like  the  following. 
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Displayed  Dots 


Binary 


Decimal 


00011000 

24 

00111100 

60 

01100110 

102 

01111110 

126 

01100110 

102 

01100110 

102 

01100110 

102 

00000000 

0 

Here,  for  comparison,  is  the  checkerboard  character. 


Displayed  Dots 


1^ 


Binary 

11001100 
00110011 
11001100 
00110011 
11001100 
00110011 
11001100 
00110011 


Decimal 

204 

51  ' 
204 

51 
204 

51 
204 

51 


Notice  that  the  checkerboard  character's  dots  extend  to  the  edge  of  the 
matrix,  while  the  A  has  space  at  the  sides  and  bottom.  This  built-in  space  is 
the  only  space  between  adjacent  characters  on  the  screen.  The  8X8  matrices 
of  characters  displayed  on  the  screen  actually  touch  those  of  adjoining 
characters,  making  the  screen  a  continuous  field  of  dots.  Here  is  a  magnified 
view  of  a  small  section  of  the  screen. 
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This  contact  between  characters  is  what  enables  you  to  build  players 
made  up  of  multiple  characters.  This  also  means  that  you  must  include  spaces 
in  some  of  your  character  definitions.  If,  for  example,  you  wanted  to  display 
the  Greek  lambda  character  in  a  scientific  formula,  you  might  define  it  like 
this: 


Displayed  Dots  Binary  Decimal 


00000000  0 

OllOOOOO  96 

OllOOOOO  96 

00 ll 0000  48 

000 ll 000  24 

OllOllOO  108 

HOOOllO  198 

00000000  0 
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As  in  Commodore's  design,  there  is  white  space  at  the  right  and  the 
bottom  of  the  lambda.  This  makes  it  line  up  with  the  other  characters  when 
displayed. 

THE  MISSING  DOTS 

Some  quick  arithmetic  will  tell  you  that  if  there  are  8  dots  in  each  row  of  a 
character,  and  40  characters  on  each  line  of  the  screen,  this  accounts  for  only 
320  dots.  As  stated  earlier,  there  are  about  500  dots  on  each  row  of  the  TV 
screen.  What  happened  to  the  others?  Some  of  them  are  lost  because  the 
electron  beam  in  the  picture  tube  actually  sweeps  a  little  beyond  the  edges  of 
the  screen.  Some  of  them  are  taken  up  by  the  border  of  the  display.  So  even 
though  there  are  over  500  dots  on  each  line  of  the  TV  screen,  only  320  are 
available  to  you. 

FINDING  A  CHARACTER'S  DEFINITION 
IN  CHARACTER  MEMORY 

Character  definition  shapes  are  stored  in  character  memory  by  screen 
code.  The  screen  code  is,  in  effect,  a  subscript  for  the  character  memory  array. 
Like  screen  and  color  memory,  the  character  memory  "array"  is  not  a  BASIC 
variable,  but  simply  a  way  to  visualize  the  character  memory  area. 

As  mentioned  earlier,  the  eight  bytes  that  define  a  character  are  stored  in 
adjacent  locations  in  color  memory,  with  the  top  row  first  and  the  bottom  row 
last.  Here  is  how  the  first  few  bytes  of  Commodore's  built-in  character 
memory,  which  starts  at  location  53248  in  C-64  mode  and  at  4096  in  C-128 
mode,  are  used. 

Location  Contents 

53248  Top  row  of  "@" 

53249  Second  row  of  "@" 

53250  Third  row  of  "@" 

53251  Fourth  row  of  "@" 

53252  Fifth  row  of  "@" 

53253  Sixth  row  of  "@" 

53254  Seventh  row  of  "@" 

53255  Bottom  row  of  "@" 

53256  Top  row  of  A 

53257  Second  row  of  A 


53263 


Bottom  row  of  A 
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53264  Top  row  of  B 

53265  Second  row  of  B 


This  layout  of  character  memory  uses  the  following  formula  to  find  the 
definition  of  a  particular  row  for  a  given  character: 

Location  =  start  of  character  memory  +  row  +  8  *  screen  code 


EXPLORING  CHARACTER  MEMORY 

Examining  the  contents  of  character  memory  requires  a  bit  of  "trickery." 
Having  the  character  ROM  memory  available  all  the  time  would  take  up 
valuable  memory  space.  Since  most  programs  don't  look  at  it  anyway,  Com- 
modore designed  the  C-128  so  that  character  memory  is  usually  hidden.  This 
leaves  an  extra  4096  bytes  available  for  programs  and  data,  but  it  also  means 
that  a  little  extra  programming  is  necessary  for  those  programs  that  do  need 
to  see  the  character  definitions. 

The  following  C-64  program  lets  you  choose  a  character  and  magnify  it  on 
the  screen.  The  program  also  displays  other  information  —  such  as  where  the 
character  resides  in  character  memory,  and  the  decimal  values  of  the  rows  — 
that  will  help  you  become  more  familiar  with  how  characters  are  designed. 

100  POKE  52,128  :  POKE  56..  128  =  CLR 
110  REM  COPV  CHARACTER  MEMORV  ROM  TO  RAN 
120  POKE  56334, PEEK (56334)  AND  254 
130  POKE  l.PEEKCl)  AND  251 

140  FOR  1*0  TO  2047 -POKE  32768+1 , PEEK (53248+ I >    :  NEXT 

150  POKE  1,PEEK(1>  OR  4 

160  POKE  56334 .PEEK (56334)  OR  1 

170  PIX*<0>-"  "jpix*<i>-"a  1" 

180  PRINT M IXH  ARACTER  MAGNIFIER" 

190  REM  GET  A  CHARACTER 

200  PRINT  "SELECT  A  CHARACTER" ; 

210  GET  KV*:IF  KV**""  THEN  210 

220  GOSUB  490 

230  REM  IGNORE  UNPRINTABLE  CHARACTERS 
240  IF  SC*128  THEN  210 

250  REM  FIND  CHARACTER'S  DEFINITION  IN  CHARACTER  MEMUKV 

260  CB=32768+8*SC 

270  PRINT  " IXH ARACTER :   " ; KV* 

280  PRINT  "ASCII  VALUE :  M;ASC<KV*> 

290  PRINT  "SCREEN  VALUE'  "JSC 

300  PRINT  "CHARACTER  STARTS  AT:  ";CB 

310  PRINT 

320  REM  PRINT  MAGNIFIED  VIEW 
330  PRINT  "llfl 
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340  FOR  I»CB  TO  CB+7 
350  ROU«PEEK<I> 

360  FR**R  I  GHT$  i  <  "  "  +STR*  <  ROW )  >  ,  6 ") 

370  OSSa'lM  KT 

380  REM  TRRNSLRTE  R  ROW  OF  BITS  TO  R  STRING 

390  FOR  J*7  TO  0  STEP  -1 

400  BIT=SON<ROW  AND  2tJ> 

410  OS**QS$+PIX$<BIT) 

420  NEXT  J 

430  OS*=OS*+l,IW  KJ" 

440  PRINT  OS*+FR* 

450  NEXT  I 

460  PRINT  "lid  rr 

470  PR I NT: PR I NT: PR I NT: GOTO  200 

480  REM  TRRNSLRTE  KEVSTROKE  TO  SCREEN  CODE 

490  SC*flSC<KV*> 

500  IF  SC  <  32  THEN  SO  128:  RETURN 
510  IF  SC  <  64  THEN  RETURN 
520  IF  SC  <  96  THEN  SOSC-64:  RETURN 
530  IF  SC  <  128  THEN  SOSC-32   =  RETURN 
540  IF  SC  <  160  THEN  S0128:  RETURN 
550  IF  SC  <  192  THEN  SOSC-64   :  RETURN 
560  IF  SC  <  255  THEN  SOSC-128:  RETURN 
570  S094:  RETURN 

The  tricky  part  is  in  lines  120-160  of  the  program.  They  make  the 
contents  of  the  character  ROM  chip  visible  and  copy  them  into  locations 
20480  through  24575. 

This  program  will  also  be  helpful  in  providing  practical  examples  for  the 
next  section,  so  you  should  save  a  copy  of  it. 

To  view  the  character  set  in  C- 128  mode,  enter  this  program.  Note  the  use 
of  the  BANK  command:  it  makes  the  process  of  reading  the  characters  from 
BANK  14  much  easier. 

10  A*(0)="  " 

20  A* ( 1 ) =CHR* (18) +CHR* ( 32 ) +CHR* (146) 
30  BANK  14 

40  FOR  R=53248  TO  53248  +  4096 

50  B=PEEK(R) 

60  FOR  J=7  TO  0  STEP  -1 

70  BIT=SGN(B  AND  2TJ) 

80  OS*=OS*+A*(BIT) 

90  NEXT  J 

100  PRINT  OS* 

110  0S*=,,n 

120  NEXT  R 


Designing  Characters 


A  good  way  to  start  designing  characters  is  with  a  sheet  of  graph  paper  (4  or  5 
lines  per  inch  works  best).  Draw  a  square  enclosing  an  area  with  eight  boxes 
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on  each  side  to  match  the  C-128's  8X8  character  matrix.  Then  number  the 
columns  so  that  your  worksheet  looks  like  this: 


1 

2 

6 

3 

1 

8 

4 

2 

6 

8 

4 

2 

1 

You  now  have  an  area  that  corresponds  to  one  character  on  the  screen, 
with  each  box  representing  one  dot. 

Now  fill  in  the  boxes  for  the  dots  that  should  be  "on"  (set  to  the  character 
color).  Here  is  an  example  of  a  simple  character. 


When  you  are  satisfied  with  the  dot  pattern,  calculate  the  values  of  the 
rows  in  screen  memory.  For  each  row,  add  the  numbers  at  the  top  of  those 
columns  whose  dots  are  "on."  Here  are  the  values  for  our  stick  man. 
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Your  new  character  is  now  ready  for  a  screen  test. 

USING  YOUR  CHARACTERS 
ON  THE  C-128 

To  use  your  custom  characters  on  the  C-128,  there  are  three  steps  you 
must  take: 

1.  Your  program  must  set  aside  an  area  in  memory  to  hold  your 
character  memory. 

2.  Your  character  patterns  must  be  loaded  into  character  memory. 

3.  Your  program  must  tell  the  V1C-II  chip  to  start  using  your  character 
memory  instead  of  Commodore's. 

In  order  to  simplify  your  initial  experiments,  you  can  start  by  making  a 
copy  of  Commodore's  characters,  replacing  them  one  by  one  with  your  own. 
To  get  started,  enter  and  run  the  following  C-64  mode  program: 

100  REM  RESERVE  MEMORY 

110  POKE  52,128   :  POKE  56,128   ■'  CLR 

120  REM  POINT  VIC- 1 1  RT  NEW  SCREEN 

130  POKE  56576, C PEEK < 56576)  AND  252>  OR  1 

140  POKE  53272,32 

150  REM  POINT  BASIC  AT  NEW  SCREEN 

160  POKE  648,136 

170  PRINT  "naBflBCDEFOHIJKLMNOPQRSTUVWXYZCfiDt*-!'1; 

180  PRINT  CHR*<34>;CHR*O4>jCHR*C20>J 

190  PRINT  "MJi^Om+i-."; 

200  PRINT  V012345fi789 :;<*>?" ■ 

210  REM  COPY  CHARACTER  MEMORY  ROM  TO  RAM 


.RAPHICS  195 


220  POKE  56334, PEEK (56334)  AND  254 
230  POKE  1 j PEEK  < 1 )  AND  251 

240  FOR  1*0  TO  2047: POKE  32768+1 , PEEK (53248+ I )    :  NEXT 

250  POKE  1,PEEK<1>  OR  4 

260  POKE  56334 »  PEEK ( 56334  >  OR  1 

Here  is  a  line-by-line  examination  of  this  program.  Line  110  changes  two 
of  BASIC'S  internal  pointers  to  make  it  appear  that  less  program  memory  is 
available.  (The  method  for  choosing  this  POKE  value  will  be  explained  later.) 
It  also  includes  a  CLR  statement,  which  forces  BASIC  to  erase  any  variables 
that  have  been  defined  and  to  adjust  its  other  internal  pointers  to  the  reduced 
memory  size.  The  POKEs  and  CLR  must  be  done  before  any  variables  are 
defined  in  the  program,  or  the  values  assigned  to  those  variables  will  be  lost.  It 
is  best  to  make  this  statement  the  first  one  in  any  program  that  defines  its  own 
characters. 

Lines  130  and  140  tell  the  VIC-II  chip  that  screen  memory  starts  at 
location  34816,  and  character  memory  at  location  32768.  When  these  state- 
ments are  executed,  the  characters  on  the  screen  will  change  to  gibberish 
because  you  have  not  yet  filled  in  your  character  definitions.  Line  160  updates 
location  648  so  BASIC  can  find  the  new  screen  memory. 

Lines  170  through  200  set  up  an  area  in  screen  memory  where  you  can  see 
the  results  of  changing  character  memory  by  PRINTing  the  characters  that 
will  use  your  custom  character  set. 

Lines  220  through  260  load  the  new  character  memory  with  the  upper- 
case and  graphics  characters  from  the  Commodore  set.  This  will  take  several 
seconds.  When  the  program  starts  copying  the  reversed  characters,  you  can 
see  the  characters  in  the  top  lines  change  as  their  definitions  are  filled  in. 

The  program  can  copy  both  the  nonreversed  and  reversed  characters 
because  the  C-128  generates  its  cursor  by  turning  bit  7  (the  "reverse"  bit)  in  the 
character  OFF  and  ON.  If  you  had  copied  just  the  nonreversed  characters,  the 
characters  under  the  cursor  would  be  changing  from  the  normal,  nonreversed 
character  to  gibberish,  because  the  reversed  portion  of  character  memory 
would  not  be  filled  in.  If  you  are  operating  in  C-128  mode,  you  can  enter  this 
simplified  version  of  the  program  instead  of  the  one  just  given. 

10  FOR  R=53248  TO  53248+4096 

20  BANK  14 

30  E=PEEK  (R) 

40  BANK  15 

50  POKE  R-45056,  E 

60  NEXT 

70  BANK  15 

80  POKE  2604,  24 
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In  the  examples  that  follow,  the  changes  will  be  made  in  the  reversed 
characters,  leaving  the  normal  characters  intact.  This  will  make  program 
listings  and  immediate  mode  statements  readable  on  the  screen. 

For  the  first  experiment,  youll  replace  the  @  sign  with  the  stick  man 
character.  To  change  the  character  memory  for  @,  enter  the  following  POKE 
statements.  You  should  type  the  POKE  statement  once  and  keep  reusing  it 
with  screen  editing  to  avoid  rolling  the  sample  characters  off  the  top  of  the 
screen. 

POKE  33792,  60 
POKE  33793,  60 
POKE  33794,  24 
POKE  33795,255 
POKE  33796,  60 
POKE  33797,  60 
POKE  33798,102 
POKE  33799,195 

As  each  POKE  is  entered,  one  row  of  the  @  character  is  changed,  until 
the  @  sign  is  replaced  with  the  stick  man.  Press  CTRL-RVS  ON,  then  @;  the 
C-64  will  display  a  stick  man.  Press  the  CRSR  LEFT  key  until  the  cursor  is  over 
the  stick  man.  Instead  of  changing  back  and  forth  between  reversed  and 
nonreversed  @  signs,  the  character  changes  from  @  to  the  stick  man  and 
back. 

Now  you're  ready  to  experiment  with  characters  of  your  own  design. 
Simply  follow  the  steps  outlined  here:  POKE  the  values  you  calculate  on  the 
worksheet  into  character  memory,  and  use  CTRL-RVS  ON  to  make  the  C-128 
display  your  character.  Experiment  with  several  characters  before  putting 
them  to  work  in  programs. 


Design  Aids  for  Custom  Characters 

If  you  expect  to  make  extensive  use  of  custom  characters,  you  will  find  it 
helpful  to  have  a  character  editor  utility  to  help  you.  Such  a  program  should 
display  the  character  in  both  normal  and  magnified  views,  allow  you  to 
change  individual  dots,  and  calculate  the  POKE  values  and  locations  for  you. 
You  can  write  your  own  utility  or  you  can  purchase  one. 

If  you  wish  to  write  your  own  utility,  several  parts  of  the  program  can  be 
taken  from  the  examples  in  Chapters  5  and  6  of  this  book.  The  Character 
Magnifier  program  in  this  chapter  can  be  used  to  display  the  character,  and 
the  Moving  Dot  program  can  be  used  as  a  base  for  the  subroutine  to  change 
the  dots.  (Hint:  use  a  delay  loop  to  flash  the  magnified  dot  off  and  on,  and 
use  the  Fire  button  on  the  joystick  to  change  the  dots.) 
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If  you  plan  to  use  custom  characters  only  occasionally,  using  the  work- 
sheet to  lay  out  your  characters  and  calculating  the  POKE  values  by  hand 
should  be  sufficient. 

Writing  Programs  that  Make  Use 
Of  Custom  Charaoters 

Once  you  have  your  characters  defined,  you  will  want  to  put  them  to  work  for 
you  in  programs.  Programs  that  use  custom  characters  are  not  much  different 
from  those  that  use  the  standard  character  set.  You  still  have  the  option  of 
using  either  PRINT  or  POKE  (or  both)  to  build  your  displays.  There  are  two 
differences,  however:  the  reduced  memory  available,  and  the  absence  of  the 
standard  character  set. 

HOW  TO  HANDLE  MEMORY  LOSS 

Custom  characters  use  up  memory  in  two  ways.  Some  memory  must  be 
set  aside  as  character  memory.  In  the  examples,  an  area  of  8192  bytes  in  C-64 
mode  and  4096  bytes  in  C-128  mode  is  used  for  the  sake  of  simplicity,  but  you 
can  reduce  that  considerably. 

Memory  is  also  needed  to  hold  the  program  and  DATA  statements  to 
load  your  custom  characters.  This  loss  will  not  be  large  if  you  use  only  a  few 
characters,  but  it  can  be  significant  if  you  are  defining  many.  A  DATA 
statement  to  hold  a  custom  character  definition  will  use  from  25  to  40  bytes, 
depending  on  the  number  of  digits  in  its  values.  Remember  that  spaces  in  a 
DATA  statement  are  stored  with  the  program,  so  you  can  reduce  the  amount 
of  memory  used  by  eliminating  them.  While  it  is  generally  recommended  that 
you  use  spaces  in  your  programs  to  improve  readability,  the  commas  that 
separate  the  values  in  DATA  statements  can  do  that  job  adequately. 

You  can  make  more  memory  available  to  your  main  program  by  splitting 
it  into  two  programs:  one  to  build  the  characters  and  one  to  do  the  main 
work.  If  you  run  the  character  builder  first,  the  program  can  be  replaced  by 
the  main  program  when  it  is  finished.  You  can  even  do  this  automatically  by 
placing  a  LOAD  statement  in  the  character  builder.  If  you  are  loading  the 
program  from  tape,  save  the  character  builder  first,  then  the  main  program 
(the  order  does  not  matter  on  a  disk  drive).  Make  the  last  two  statements  of 
the  character  builder  a  CLR  and  a  LOAD. 

100  REM  LOAD  CUSTOM  CHARACTERS 
HO  DATA  5,12,17,32 
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340  REM  PROTECT  MEMORY 
350  POKE  52,128  :  POKE  56,128 
360  REM  FORGET  VARIABLES 
370  CLR 

380  REM  GET  TO  WORK 
390  LOAD  "MAIN" 

The  C-128  will  load  and  run  the  program  called  MAIN.  The  CLR  is 
needed  to  erase  any  variables  defined  in  the  character  builder.  BASIC  stores 
variables  in  memory  immediately  after  the  program  text.  Because  your  main 
program  will  probably  be  larger  than  the  character  builder,  part  of  it  will  be 
stored  in  the  area  occupied  by  the  character  builder's  variables.  If  the  CLR 
were  not  there,  and  you  had  a  variable  in  the  main  program  with  the  same 
name  as  one  in  the  character  builder,  BASIC  might  store  values  assigned  to 
that  variable  in  the  program's  area.  The  result  of  damaging  a  program  this 
way  is  unpredictable,  but  you  can  avoid  it  easily:  always  include  the  CLR 
statement  before  the  LOAD,  telling  BASIC  to  "forget"  the  old  variables. 

ACCESSING  THE  BUILT-IN  CHARACTER  SET 

Your  program  may  also  need  to  work  around  the  loss  of  the  standard 
character  set.  If  your  program  displays  messages,  you  have  two  choices:  if 
you  are  not  redefining  all  256  characters,  simply  leave  the  alphabetic  charac- 
ters intact.  If  you  do  need  256  characters,  you  can  switch  back  and  forth 
between  your  custom  characters  and  the  built-in  character  set. 

Messages  from  BASIC  itself  may  still  be  a  problem.  If  you  redefine  the 
alphabetic  characters  to  build  players,  a  simple  READY  message  may  look 
like  Egyptian  hieroglyphics.  This  should  not  cause  any  serious  difficulty 
except  when  you  are  debugging  your  program.  If  you  interrupt  it  with  the 
STOP  key,  or  if  BASIC  finds  an  error,  the  messages  produced  may  be  some- 
what difficult  to  read.  You  can  return  to  the  normal  character  set  by  entering 
the  statements  later  in  this  chapter  to  switch  back  and  forth  between  character 
sets  from  the  keyboard.  You  should  also  note  that  RUN/ STOP-RESTORE  will 
bring  back  the  normal  character  set  but  also  leave  your  custom  character 
memory  intact  and  still  protected  from  BASIC.  Unfortunately,  it  will  also 
clear  the  screen  and  erase  the  error  message,  so  it's  not  very  useful  while  you 
are  debugging  programs. 

Animating  Players 

A  player  built  from  custom  characters  can  be  made  to  move  by  modifying  its 
patterns  in  character  memory,  but  this  technique  will  usually  be  too  slow  if 
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done  in  BASIC.  (Machine  language  programs  can  run  fast  enough  to  handle 
it.)  A  simpler  and  faster  approach  is  to  define  more  than  one  version  of  the 
player  in  character  memory.  Your  program  can  then  make  it  move  by  chang- 
ing the  version  displayed  with  a  POKE  to  screen  memory. 

As  an  example  of  this  method  of  animation,  here  is  the  stick  man.  Put  a 
little  meat  on  his  bones  by  building  him  with  nine  characters  instead  of  one. 


To  liven  him  up  a  bit,  make  him  wave  one  arm  by  defining  two  more 
versions  of  the  character  that  contains  it. 


To  observe  him  in  action,  enter  the  following  program  in  C-64  mode: 


100  REM  RESERVE  MEMORY 

110  POKE  52,128   :  POKE  56,128  :  CLR 
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120  REM  POINT  VIC- 1 1  RT  NEW  SCREEN  AND  CHRRRCTER  MEMORV 

130  POKE  56576, < PEEK < 56576)  AND  252)  OR  1 

140  POKE  53272,32 

150  REM  POINT  BASIC  RT  NEW  SCREEN 

160  POKE  648,136 

170  REM  COPV  CHRRRCTER  MEMORV  ROM  TO  RRM 
190  POKE  56334 , PEEK  < 56334 )  AND  254 
190  POKE  1, PEEK <1)  AND  251 

200  FOR  1=0  TO  2047: POKE  32768+1 , PEEK < 53246+ I )   :  NEXT 

210  POKE  1 ,  PEEKd  )  OR  4 

220  POKE  56334, PEEK (56334)  OR  1 

230  REM  CLEAR  SCREEN  AND  SET  UP  DISPLAV  AREA 

240  DLV=250   :  SB=34816 

250  PRINT  "IMlfiB" 

260  PRINT  "SCDE" 

265  PRINT  " SFGH" 

270  REM  LOAD  BASIC  PL AVER 

280  FOR  1=33792  TO  33863  :  READ  X   :   POKE  I,X  :   NEXT  I 

290  DATA  0,0,0,0,0,0,0,0 

300  DATA  28,62,62,62,62,28,62,255 

310  DATA  96,96,96,96,96,96,96,96 

320  DATA  3,6,6,6,6,6,0,0 

330  DATA  255,255,255,255,255,255,126,102 

340  DATA  192,0,0,0,0,0,0,0 

350  DATA  0,0,0,0,0,0,0,0 

360  DATA  102,102,102,102,231,0,0,0 

370  DATA  0,0,0,0,0,0,0,0 

380  REM  LOAD  'EXTRA  ARMS' 

390  FOR  I =33864  TO  33879   :   READ  X   :   POKE  I, X   :   NEXT  I 

400  DATA  0,0,3,6,12,24,48,224 

410  DATA  0,0,0,0,0,0,255,255 

420  POKE  SB+2,130 

430  FOR  1=1  TO  DLV  :  NEXT  I 

440  POKE  SB+2,137 

450  FOR  1*1  TO  DLV   :   NEXT  I 

460  POKE  SB+2,138 

470  FOR  1=1  TO  DLV  :  NEXT  I 

480  POKE  SB+2,137 

490  FOR  1=1  TO  DLV  :  NEXT  I 

500  GOTO  420 

When  you  run  this  program,  the  new  stick  man  will  be  placed  in  the 
upper-left  corner  of  the  screen,  and  his  arm  will  begin  to  wave. 

NOTE:  There  is  a  long  delay  preceding  the  action  in  this  program. 
Here's  the  C-128  version  of  the  waving  stick  man: 

10  FOR  R-53248  TO  57344 

20  BANK  14 

30  E=PEEK  (R) 

40  BANK  15 

50  POKE  R-45056,  E 

60  NEXT 

70  BANK  15 

80  POKE  2604,  24 

90  REM  LOAD  BASIC  PLAYER 
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100  FOR   1=8192  TO  8255 

110  READ  X:    POKE   I,X:    NEXT  I 

120  DATA  0,0,0,0,0,0,0,0 

130  DATA  28,62,62,62,62,28,62,255 

140  DATA  96,96,96,96,96,96,96,96 

150  DATA  3,6,6,6,6,6,0,0 

160  DATA  255, 255, 255, 255, 255, 255, 126, 102 

170  DATA  192,0,0,0,0,0,0,0 

180  DATA  0,0,0,0,0,0,0,0 

190  DATA   102, 102, 102, 102, 231 ,0,0,0 

200  REM  LOAD    'EXTRA  ARMS' 

210  FOR   1=8256  TO  8271 

220  READ  X:    POKE   I,X:   NEXT  I 

230  DATA  0,0,3,6,12,24,48,244 

240  DATA  0,0,0,0,0,0,255,255 

250  REM  DISPLAY  CHARACTER 

260  PRINT  CHR* ( 147) ; "@AB" 

270  PRINT   "CDE " 

280  PRINT  "FG" 

290  A*  (0)-="  I  "  :  A*  C 1 )  ="H"  :  A*  (2)  =,'B"  :  A*  (3)  =,'H" 

300  FOR  R=0  TO  3 

310  PRINT  CHR*(19) ;CHR*(29) ;CHR*(29) ; A*(R) ; 
320  FOR  U=0  TO  250:  NEXT 
330  NEXT  R:    GOTO  300 
340  END 


MORE  COMPLEX  ANIMATION 

While  the  C-128  is  capable  of  much  more  complex  animation  than  the 
stick  man  example  shows,  the  techniques  are  the  same.  Your  program  can,  for 
example,  have  several  players  in  motion  at  once,  or  have  one  player  making 
different  motions  simultaneously.  Either  of  these  can  be  done  by  predefining 
the  movements  with  several  custom  characters. 

Here  is  a  C-64  mode  example  of  two  players  in  motion  at  once.  Youll 
create  another  stick  man  who  will  wave  to  the  first  one.  Change  the  stick  man 
program  so  that  it  looks  like  this: 

10  REM  RESERVE  MEMORY 

100  CLR : P0KE52 .128: P0KE56 >  128 : CLR 

110  G08IJE  10020 

120  REM  LEFT  MAN  WAVES 

130  FOR  J*=l  TO  2   :   GOSUB  220   :   NEXT  J 

140  REM  BOTH  MEN  WAVE 

150  FOR  J*l  TO  5   :   GOSUB  320   :   NEXT  J 

160  REM  RIGHT  MAN  WAVES 

170  FOR  J=l  TO  2   :   GOSUB  500   :   NEXT  J 

180  REM  BOTH  MEN  REST 

190  FOR  J=l  TO  1000  :  NEXT  J 

200  GOTO  130 

210  REM  WAVE  LEFT  MAN'S  ARM  ONLY 

220  POKE  SB+2,130 

230  FOR  1=1  TO  DLV  :  NEXT  I 
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240  POKE  SB+2,137 

250  FOR  1*1  TO  DLV   :   NEXT  I 

260  POKE  SB+2,138 

270  FOR  1=1  TO  DLV  :  NEXT  I 

280  POKE  SB+2,137 

290  FOR  1  =  1  TO  DLV   :   NEXT  I 

300  RETURN 

310  REM  WAVE  BOTH  MEN'S  ARMS 

320  POKE  8B+2,130 

330  FOR  '1  =  1  TO  DLV/2   :   NEXT  I 

340  POKE  SB+8,137 

350  FOR  1=1  TO  DLV/2   :   NEXT  I 

360  POKE  SB+2,137 

370  FOR  1=1  TO  DLV/2   :   NEXT  I 

380  POKE  SB+8,138 

390  FOR  1=1  TO  DLV/2  :  NEXT  I 

400  POKE  SB+2,138 

410  FOR  1=1  TO  DLV/2  :  NEXT  I 

420  POKE  SB+8,137 

430  FOR  1=1  TO  DLV/2  =  NEXT  I 

440  POKE  SB+2,137 

450  FOR  1=1  TO  DLV/2  :  NEXT  I 

460  POKE  SB+8,130 

470  FOR  1=1  TO  DLV/2  :  NEXT  I 

480  RETURN 

490  REM  WAVE  RIGHT  MAN'S  ARM  ONLV 

500  POKE  SB+8,137 

510  FOR  1=1  TO  DLV   :   NEXT  I 

520  POKE  SB+8,138 

530  FOR  1=1  TO  DLV   :   NEXT  I 

540  POKE  SB+8,137 

550  FOR  1  =  1  TO  DLV      NEXT  I 

560  POKE  SB+8,130 

570  FOR  1=1  TO  DLV  :  NEXT  I 

580  RETURN 

590  REM  INITIALIZATION 

600  REM  SET  DELAV  LOOP  LENGTH 

610  DLV* 100 

10020  REM  POINT  VIC- 1 1  AT  NEW  SCREEN  AND  CHARACTER  MEMORV 

10030  POKE  56576, (PEEK (56576)  AND  252)  OR  1 

10040  POKE  53272,32 

10050  REM  POINT  BASIC  AT  NEW  SCREEN 

10060  POKE  648,136 

10070  REM  COPV  CHARACTER  MEMORV  ROM  TO  RAM 
10080  POKE  56334, PEEK(56334)  AND  254 
10090  POKE  1,PEEK(1)  AND  251 

10100  FOR  1=0  TO  2047:  POKE  32768+1 ,  PEEK  (53248+ 1 )    :  NEXT 

10110  POKE  1,PEEK(1)  OR  4 

10120  POKE  56334, PEEK (56334)  OR  1 

10130  REM  CLEAR  SCREEN  AND  SET  UP  DISPLAV  AREA 

10140  DLV=250  :  SB=34816 

10150  PRINT  "HSOlABi      MA  J" 

10160  PRINT  "SJCDEl  3CDE" 

10170  PRINT  "  SFGHi  SFGH" 
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10180  REM  LORD  BASIC  PLflVER 

10190  FOR  1=33792  TO  33863   :  READ  X   :   POKE  I,X   :   NEXT  I 

10191  REM 

10200  DATA  0,0,0,0,0,0,0, 1 

10210  DATA  28,62,62,62,62,28,62,255 

10220  DATA  96,96,96,96,96,96,96,224 

10230  DATA  3,6,6,6,6,6,0,0 

1 0240  DATA  255 , 255 , 255 , 255 , 255 , 255 ,  1 26 , 1 02 

10250  DATA  192,0,0,0,0,0,0,0 

10260  DATA  0,0,0,0,0,0,0,0 

10270  DATA  102,102,102,102,231,0,0,0 

10280  DATA  0,0,0,0,0,0,0,0 

10290  REM  LOAD  'EXTRA  ARMS"' 

10300  FOR  1=33864  TO  33879   :  READ  X   :   POKE  I,X   :   NEXT  I 
10310  DATA  0,0,3,6,12,24,48,224 
10320  DATA  0,0,0,0,0,0,0,255 
10330  RETURN 

The  C-128  mode  version  of  this  program  looks  like  this: 

10  FOR  R=53248  TO  57344 

20  BANK  14 

30  E=PEEK  (R) 

40  BANK  15 

50  POKE  R-45056,  E 

60  NEXT 

70  BANK  15 

80  POKE  2604,  24 

90  FOR   1=8192  TO  8255 

100  READ  X:    POKE   I,X:   NEXT  I 

110  DATA  0,0,0,0,0,0,0,0 

120  DATA  28,62,62,62,62,28,62,255 

130  DATA  96,96,96,96,96,96,96,96 

140  DATA  3,6,6,6,6,6,0,0 

150  DATA  255,255,255,255,255,255,126,102 

160  DATA  192,0,0,0,0,0,0,0 

170  DATA  0,0,0,0,0,0,0,0 

180  DATA  102,102,102,102,231,0,0,0 

190  FOR   1=8256  TO  8271 

200  READ  X:   POKE  I,X:   NEXT  I 

210  DATA  0,0,3,6,12,24,48,244 

220  DATA  0,0,0,0,0,0,255,255 

230  PRINT  CHR$ ( 147) ; "@AB  @AB" 

240  PRINT   "CDE  CDE" 

250  PRINT  "FG  FG" 

260  R2*=CHR* (19) +CHR* ( 29 ) +CHR* ( 29 ) 

270  FOR  0=0  TO  4: R5*=R5*+CHR* (29)  s  NEXT 

280  R9*=R2*:  F0R0=0T05:  R9*=R9*+CHR*  (29)  :  NEXT 

290  A* (0) =" I " : A* ( 1 ) ="H" : A* (2) ="B" : A* (3) ="H" 

300  FOR  R=0  TO  3 

310  PRINT  R2*;A*(R); 

320  FOR  U=0  TO  250:  NEXT 

330  NEXT  R 

340  FOR  R=0  TO  3 

350  PRINT  R9*;A*(R); 
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360  FOR  U=0  TO  250:  NEXT 

370  NEXT  R 

380  FOR  R=0  TO  3 

390  PRINT  R2*;A*(R) ;R5*;A*(R) 

400  FOR  U=0  TO  250:  NEXT 

410  NEXT  R:GOTO  300 

When  you  run  the  C-64  mode  program,  the  stick  man  on  the  left  side  of 
the  screen  starts  waving.  After  a  moment,  the  one  at  the  right  starts  to  wave 
back.  Then  the  man  on  the  left  stops  waving,  followed  by  the  one  on  the  right, 
and  the  cycle  repeats. 

The  three  subroutines  that  make  the  men  wave  (lines  210,  310,  and  490) 
are  the  key  to  the  motion.  The  first  one,  starting  at  line  210,  makes  only  the 
figure  on  the  left  wave. 

The  second  subroutine,  which  begins  with  line  310,  causes  both  of  the 
men  to  wave.  Notice  that  the  man  on  the  left  moves,  and  then  the  program 
pauses  for  about  half  the  time  it  did  when  moving  just  one  arm  before  moving 
the  man  on  the  right.  After  the  right-hand  man's  arm  moves,  the  program 
again  delays  only  half  as  long  as  before.  This  keeps  the  men  moving  at  about 
the  same  speed,  even  though  both  are  waving  together.  The  man  on  the  right 
also  waves  in  the  opposite  direction  from  the  man  on  the  left,  so  they  don't 
appear  to  be  moving  in  "lock-step"  with  each  other.  These  small  differences 
make  the  display  more  interesting. 

The  last  subroutine,  starting  at  line  490,  moves  only  the  right-hand  stick 
man,  so  the  one  on  the  left  stops  waving. 

When  you  run  the  C-128  version  of  the  program,  the  stick  men  behave 
just  as  they  did  before.  Once  again,  the  three  subroutines  that  make  the  men 
wave  (lines  300, 340,  and  380)  are  the  key  to  the  motion.  The  first  one,  starting 
at  line  300,  makes  only  the  figure  on  the  left  wave. 

The  second  subroutine,  which  begins  with  line  340,  causes  the  right  man 
to  wave.  Notice  that  the  men  move  at  about  the  same  speed  even  though  both 
are  waving  together.  Also,  in  this  routine,  the  man  on  the  right  waves  in  the 
same  direction  as  the  man  on  the  left,  so  they  appear  to  be  moving  in 
"lock-step"  with  each  other. 

The  last  subroutine,  starting  at  line  380,  moves  both  the  right-hand  stick 
man  and  the  left-hand  stick  man. 

C-64  MODE  BIT-MAPPED  GRAPHICS 


With  bit-mapped  graphics,  your  program  manipulates  individual  dots  on  the 
screen  instead  of  whole  characters.  Bit-mapping  gets  its  name  from  the  fact 
that  there  is  an  area  in  memory  set  aside  to  represent  the  contents  of  the  screen 
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on  a  dot-by-dot  basis.  Just  as  cities,  parks,  and  airports  are  represented  by 
symbols  on  a  geographic  map,  dots  on  the  screen  are  represented  by  bits  in 
memory.  Bit-mapping  can  be  used  to  draw  finer  lines  on  the  screen  or  to 
smooth  the  motion  of  a  player,  since  it  can  move  in  increments  of  one  dot 
instead  of  a  whole  character  space. 

Using  bit-mapped  graphics  on  the  C-128  in  C-64  mode  is  much  like  using 
custom  characters.  The  VIC-II  chip  handles  them  in  almost  exactly  the  same 
way:  in  each  case,  it  looks  up  the  contents  of  an  8X8  dot  "cell"  in  a  table  and 
displays  the  dots  one  row  at  a  time.  The  difference  lies  in  how  the  VIC-II 
decides  where  to  look  in  the  table;  in  a  character  display,  it  uses  the  value  in 
screen  memory  (the  "screen  code"  for  the  character)  to  find  the  entry  in 
character  memory.  When  displaying  a  bit-mapped  screen,  the  VIC-II  steps 
through  the  table  sequentially.  It's  as  though  you  had  a  table  of  1000  custom 
characters,  and  the  screen  contained  screen  codes  numbered  0  through  999. 

You  can  still  use  many  of  the  concepts  and  tools  that  you  used  for  custom 
character  displays.  The  main  difference  is  one  of  programming  technique. 
Using  custom  characters,  you  set  up  the  character  memory  and  change  the 
display  by  altering  screen  memory.  In  bit-mapped  displays,  "screen  memory" 
stays  constant  but  "character  memory"  changes. 

To  understand  bit-mapped  graphics,  here  is  a  review  of  the  discussion  of 
character  memory,  but  with  a  different  perspective.  From  the  point  of  view  of 
text  display,  think  of  screen  memory  as  containing  characters  to  be  displayed, 
with  character  memory  holding  the  dot  patterns  that  represent  the  characters. 
In  bit-mapped  (high-resolution)  terms,  character  memory  becomes  a  dot-by- 
dot  representation  of  the  display,  and  screen  memory  is  replaced  by  a  counter 
to  remind  the  VIC-II  chip  of  where  it  is  on  the  screen.  In  both  cases,  the 
VIC-II  chip  is  doing  exactly  the  same  thing:  looking  up  dot  patterns  in 
character  memory  and  displaying  them  on  the  screen.  Only  the  method  for 
finding  the  dot  pattern  in  the  table  process  is  different.  Recall  how  one  player 
was  built  from  several  custom  characters  in  the  last  section.  You  can  think  of 
bit-mapped  graphics  as  using  the  entire  screen  as  a  single  "super  player." 

High-resolution  graphics  have  two  drawbacks.  First,  they  use  a  large 
amount  of  memory:  to  map  the  screen  in  high-resolution  mode  completely 
takes  8000  bytes  of  character  memory.  Second,  in  C-64  mode,  bit-mapping  is 
an  all-or-nothing  proposition:  you  can't  have  bit-mapped  graphics  and  a 
character  display  on  the  screen  at  the  same  time.  It  is  possible,  however,  to 
experiment  with  high  resolution  without  losing  the  character  display.  Since 
the  bit-mapped  display  is  so  similar  to  a  custom  character  display,  you  can 
create  a  mini-bit-mapped  display  using  only  a  small  portion  of  the  screen.  The 
techniques  used  for  defining  a  custom  character  set  can  also  be  used  to  set  up 
a  64X64  dot  area  for  bit-mapping  experimentation. 
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The  steps  in  preparing  this  bit-mapped  work  area  are  similar  to  those  for 
establishing  a  custom  character  set.  The  Setup  program  listed  here  may  seem 
familiar,  because  it  was  written  by  making  some  editing  changes  to  the 
program  used  to  set  up  the  custom  character  work  area. 

100  REM  HIGH  RESOLUTION  "SETUP"  PROGRAM 
110  REM  PROTECT  CHARACTER  MEMORV 
120  POKE  52,128   :  POKE  56.128   :  CLR 

130  REM  POINT  VIC-II  AT  NEW  SCREEN  AND  CHARACTER  MEMORV 

140  POKE  56576, < PEEK (56576)  AND  252)  OR  1 

150  POKE  53272,32 

160  REM  POINT  TO  NEW  SCREEN 

170  POKE  648,136  :  SB»34816 

180  REM  COPV  CHARACTER  MEMORV  ROM  TO  RAM 

190  POKE  56334, PEEK (56334)  AND  254 

200  POKE  1,PEEK(1)  AND  251 

210  FOR  1*0  TO  1023: POKE  32768+1 , PEEK (53248+ I >    :  NEXT 

220  POKE  1,PEEK(1)  OR  4 

230  POKE  56334, PEEK (56334)  OR  1 

240  REM  CLEAR  "BIT-MAP"  AREA  IN  CHARACTER  MEMORV 
250  FOR  1*33792  TO  34303  :   POKE  1,0   :   NEXT  I 
260  REM  CLEAR  SCREEN  AND  SET  UP  WORK  AREA 
270  PRINT  "MHPX  (08" 
280  PRINT  "dHIQV! )19" 

290  PRINT  "■JRZ,,;CHR*<34>;CHR*O4)JCHR*<20>;  »'*2:  " 
300  PRINT  "UCKSC#+3j " 
310  PRINT  ,,aDLT£*i4<" 

320  PRINT  "JSEMUr/J-S*" 
330  PRINT  "  SFNVt4.fi:>" 
340  PRINT  "SG0W+-V7?" 


Now  the  upper-left  corner  of  the  screen  has  become  a  bit-mapped  work 
area  in  which  you  can  experiment. 


Changing  the  Dots 
In  the  Bit-Mapped 
Work  Area 


After  you  run  the  Setup  program,  the  portion  of  character  memory  that 
defines  the  work  area  looks  like  this: 
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Memory 
Location 


Column 


Memory 
Location 


Column 


Row 

0 

34816 

34880 

35264 

34817 

34881 

35265 

2 

34818 

34882 

35266 

3 

34819 

34883 

-"'**'  35267 

4 

34820 

34884 

35268 

60 

34876 

35240 

35324 

61 

34877 

35241 

35225 

62 

34878 

35242 

'  35226 

63 

34879 

35243 

35227 

Memory 

Location  Column 

c  r  x      C  -  r  i  ^, 


To  change  a  dot  on  the  screen,  your  program  must  find  the  right  location 
to  POKE  and  the  value  to  put  there.  The  64  bits  of  the  X  dimension  are 
broken  up  into  8  bytes  of  8  bits  each.  To  find  the  correct  column  of  bytes,  use 
the  following  formula: 

450  C0L=IMT<X/8> 

Since  each  column  of  bytes  in  the  pseudo-display  is  64  rows  high,  the 
column  number  must  be  multiplied  by  64.  The  calculation  to  find  the  right 
location  to  POKE  is 

460  PL«33792+V+64*C0L 

The  bit  within  that  byte  is  the  remainder  of  the  division  by  8  you  did  to 
find  the  column.  To  calculate  the  right  bit,  use 

460  PL=33792+V+64#C0L 
470  BIT«7-CX-C0L#e) 

You  subtracted  the  remainder  from  7  because  the  bit-mapped  columns 
are  numbered  from  left  to  right,  but  the  bits  in  a  byte  are  numbered  from  right 
to  left. 

Just  knowing  the  number  of  the  bit  is  not  enough.  Because  it  will  be  using 
POKE  to  change  the  display,  your  program  must  calculate  the  number  that 
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corresponds  to  that  bit.  Remember  that  each  bit  in  the  byte  represents  a 
power  of  2. 


Since  this  is  the  case,  you  can  easily  convert  from  the  bit  number  to  the 
POKE  value  using  the  exponentiation  operator. 

480  PV«2tBIT 

Your  program  cannot  simply  POKE  blindly  into  the  byte  it  has  found, 
because  there  are  seven  other  bits  there  that  you  don't  want  to  disturb.  To 
change  just  one  bit,  you  must  PEEK  the  byte  to  be  changed,  modify  only  the 
correct  bit,  and  then  POKE  it  back.  To  change  only  a  single  bit,  you  can  use 
the  AND  and  OR  operators.  For  example,  to  set  a  bit  to  0  (making  its  dot  the 
background  color),  you  can  use  a  variation  of  the  masking  technique  that  was 
used  to  isolate  the  bits  for  joystick  switches. 

500  POKE  PL , PEEK < PL)  RND  NOT  PV 

Notice  the  use  of  the  NOT  operator.  When  you  were  isolating  the  joystick 
switches,  you  used  the  value  of  the  bit  directly.  That  produced  a  mask  in 
which  the  bit  desired  was  a  1,  and  all  the  others  were  O's.  This  time  you  are 
using  a  mask  in  which  the  bit  you  are  interested  in  is  a  0  and  all  the  others  are 
l's.  The  AND  will  force  that  bit  to  0  and  leave  the  others  undisturbed. 
Suppose  you  want  to  turn  off  bit  3  in  location  34882,  which  currently  contains 
a  value  of  43.  You  could  use  a  BASIC  statement  like  this: 

10  POKE  34882,  PEEK  (34882)  RND  NOT  2t3 


Bit  Number 


7    6    5    4    3    2    1  0 


Value  for  POKE 


128  64  32  16    8    4    2  1 


00001000 
11110111 
AND 


00101011 


00100011 


When  you  POKE  the  result  back  into  location  34882,  only  bit  3  has 
changed.  The  other  bits  kept  their  old  values. 

To  change  the  dot  back  to  the  background  color,  use  the  OR  operator. 
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10  POKE  34882,  PEEK (34882)  OR  2t3 

^  00001000 

OR 

I   0010001 1 

 0010101 1 

As  before,  only  the  value  of  bit  3  is  changed. 

This  is  a  lot  of  work  just  to  change  one  bit.  However,  since  there  are  only 
eight  bits  in  a  byte,  there  are  only  eight  possible  values  for  the  AND  mask  and 
eight  for  the  OR  mask.  Since  there  are  only  eight  of  each  type  of  mask,  it  is 
practical  (and  much  faster)  to  calculate  them  in  advance  and  store  them  in 
tables.  The  program  fragment  that  follows  can  be  used  as  a  subroutine  in 
programs  that  produce  bit-mapped  displays.  It  creates  two  arrays  of  masks, 
called  Ml%  (Make  1)  and  M0%  (Make  0). 

100  FOR  I»0  TO  7 
110  Mltf<I>*2tI 
120  M0tf<I>==NOT  M1XCI) 
130  NEXT  I 

Notice  that  the  array  indexes,  like  the  bit  numbers,  start  with  0  because 
you  calculate  the  bit  number  using  the  remainder  of  a  division,  which  can  be 
0.  The  arrays  are  specified  as  integer  variables  because  BASIC  does  Boolean 
operations  with  integers. 

Using  these  precalculated  masks  not  only  makes  programs  faster,  but 
also  makes  them  easier  to  read.  Compare  earlier  examples  for  setting  and 
resetting  bits  with  statements  that  perform  the  same  operations  using  the 
table. 

10  POKE  34882, PEEK (34882)  AND  M0KC3) 
20  POKE  34882, PEEKC348S2)  OR  M1X<3) 

Even  with  techniques  like  precalculating  masks,  BASIC  is  usually  too 
slow  for  animation  of  bit-mapped  displays;  there  are  just  too  many  bits  to 
change  in  order  to  move  a  player  around  the  screen.  This  kind  of  high-speed 
"bit-juggling"  is  best  done  in  machine  language.  BASIC  is,  however,  quite 
useful  for  displays  that  don't  move,  such  as  drawings  and  graphs.  For  exam- 
ple, the  following  program  will  draw  a  triangle  on  the  screen: 

100  REM  HIGH  RESOLUTION  "SETUP"  PROGRAM 
110  REM  PROTECT  CHARACTER  MEM0RV 
120  POKE  52,128  :  POKE  56,128  :  CLR 

130  REM  POINT  VIC- 1 1  AT  NEW  SCREEN  AND  CHARACTER  MEM0RV 
140  POKE  56576, (PEEK (56576)  AND  252)  OR  1 
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150  POKE  53272,32 

160  REM  POINT  TO  NEU  SCREEN 

170  POKE  648,136  :  SB=3481S 

180  REM  COPV  CHARACTER  MEMORV  ROM  TO  RAM 

190  POKE  56334, PEEK (56334)  AND  254 

200  POKE  1,PEEKU>  AND  251 

210  FOR  1=0  TO  1023: POKE  32768+ 1 , PEEK  < 53248+ 1 >   :  NEXT 

220  POKE  liPEEKCl)  OR  4 

230  POKE  56334 ,  PEEK  (.  56334 )  OR  1 

240  REM  CLEAR  "BIT-MAP"  AREA  IN  CHARACTER  MEMORV 
250  FOR  1=33792  TO  34303  :   POKE  1,0   :   NEXT  I 
260  REM  CLEAR  SCREEN  AND  SET  UP  WORK  AREA 
270  PRINT  MMHPX  <08'* 
280  PRINT  "IflAIQV! )19" 

290  PR  I  NT  "  SB  JRZ "  j  CHR$  <  34 ) CHR*  ( 34 )  J  CHR %  ( 20 ) ;  "  #2  '  " 

300  PRINT  MflCKSC#+3; " 

310  PRINT  "jaDLT£*,4<" 

320  PRINT  "flEMU3X-5«" 

330  PRINT  "SFNVt&.O" 

340  PRINT  "aOOW^V??" 

350  REM  BUILD  MASK  ARRAV 

360  FOR  1*0  TO  7 : MltfCI )*2tl    :   NEXT  I 

370  REM  DRAW  BOTTOM  OF  TRIANGLE 

380  V»63 

390  FOR  X=0  TO  63 
400  QOSUB  540 
410  NEXT 

420  REM  DRAW  LEFT  SIDE  OF  TRIANGLE 
430  FOR  X*0  TO  30 
440  V  =  63~X*2 
450  OOSUB  540 
460  NEXT 

470  REM  DRAW  RIGHT  SIDE  OF  TRIANGLE 

480  FOR  X»31  TO  62 

490  V  «  63-(62-X>*2 

500  OOSUB  540 

510  NEXT 

520  END 

530  REM  BIT  SETTING  SUBROUTINE 

540  C0L«INT(X/8) 

550  PL«33792+V+64#C0L 

560  BIT«7-<X~C0L#8> 

570  POKE  PL i PEEK (PL)  OR  MltfCBIT) 

580  RETURN 


When  you  run  the  program,  you  will  see  that  the  triangle  is  drawn  much 
too  slowly  to  be  useful  in  a  fast-action  game.  It  would  be  practical,  however, 
for  use  in  an  educational  program  that  displayed  geometric  shapes. 
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Using  the  Entire  Screen 

The  techniques  discussed  in  the  last  section  work  just  as  well  for  a  full 
bit-mapped  screen.  However,  you  need  to  change  the  formulas  for  finding  the 
right  byte  to  POKE.  A  subroutine  to  do  the  calculation  might  look  like  this: 

100  PL  =  BM+(40#INT(V/8))+CV  AND  7)+INT<X/8> 

You  also  need  to  tell  the  VIC-II  to  switch  to  bit-mapped  mode.  This  is 
controlled  by  bit  5  in  location  53265.  When  this  bit  is  set  to  1,  the  VIC-II 
changes  to  a  bit-mapped  display.  The  other  bits  in  this  location  should  be 
preserved,  so  use  the  same  masking  technique  used  for  the  character  memory 
bytes. 

100  POKE  53265, PEEK (53265)  OR  32 

There  is  one  more  thing  you  need  to  know  to  use  bit-mapped  graph- 
ics: the  colors  of  the  dots  are  specified  differently  from  character  displays. 
You  may  have  wondered  what  happened  to  screen  memory  in  bit-mapped 
mode.  Remember  that  the  location  in  "character  memory"  doesn't  come  from 
screen  memory  for  bit-mapped  displays.  This  leaves  screen  memory  available 
for  other  purposes,  and  it  is  used  to  store  the  color  codes.  Just  as  for  character 
displays,  a  "0"  dot  in  a  high-resolution  display  appears  on  the  screen  in  the 
"background"  color,  and  a  "1"  dot  is  the  "character"  color.  But  screen 
memory  is  8  bits  wide,  not  4,  so  there  is  room  for  2  color  codes.  In  bit-mapped 
mode,  each  8X8  dot  "cell"  has  its  own  "background"  and  "character"  colors. 
The  "background"  color  is  stored  in  bits  0-3,  and  the  "character"  color  is  in 
bits  4-7. 


7 

6 

5 

4 

3 

2 

1 

0 

i 

1 

"Background"  color 

Used  when  a  dot  is  "0"  (off). 

"Character"  color 

Used  when  a  dot  is  "1"  (on). 


This  gives  you  more  freedom  in  mixing  colors  on  the  screen.  To  calculate 
the  value  to  POKE  for  a  given  location  on  the  screen,  use  the  formula 

100  POKE  36867 j  (PEEK (36867)  AND  127)  OR  ((SB/8)  AND  128) 
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Now  you  will  examine  how  these  techniques  work  in  a  real  program.  The 
triangle-drawing  program  has  been  modified  to  use  a  bit-mapped  screen.  If 
you  compare  it  to  the  version  that  used  custom  characters,  youH  see  that  it 
hasn't  changed  much. 

100  REM  BIT  MAPPED  DISPLRV  DEMONSTRATION  PROGRAM 
110  REM  PROTECT  BIT  MAP  MEMORV 
120  POKE  52,64      POKE  56,64   :  CLR 

130  REM  POINT  VIC- 1 1  AT  NEW  SCREEN  AND  BIT  MAP  MEMORV 
140  POKE  56576, (PEEK (56576)  AND  252)  OR  2 
150  POKE  5327fi,  8 

160  REM  SET  VIC-II  TO  BIT-MAPPED  MODE 

170  POKE  53265 , PEEK  ( 53265 )  OR  32 

180  REM  SET  POINTER  TO  BIT  MAP  AREA 

190  BM=24576  :  SB* 16384 

200  REM  CLEAR  "BIT-MAP"  AREA 

210  FOR  I*BM  TO  BM+7999   •   POKE  1,0   :   NEXT  I 

220  REM  FILL  "SCREEN"  MEMORV  WITH  COLOR  CODES 

230  FOR  I=SB  TO  SB+999  :  POKE  1,230   :   NEXT  I 

240  REM  BUILD  MASK  ARRAV 

250  FORI=0TO7:MlX<I)s2t<7-I)    :   NEXT  I 

260  REM  DRAW  BOTTOM  OF  TRIANGLE 

270  V«63 

2S0  FOR  X=0  TO  63 
290  GOSUB  530 
300  NEXT 

310  REM  DRAW  LEFT  SIDE  OF  TRIANGLE 
320  FOR  X=0  TO  30 
330  V  a  63~X*2 
340  GOSUB  530 
350  NEXT 

360  REM  DRAW  RIGHT  SIDE  OF  TRIANGLE 
370  FOR  X=31  TO  62 
380  V  =  63-(62~X)*2 
390  GOSUB  530 
400  NEXT 

410  REM  WAIT  FOR  A  KEV  TO  BE  PRESSED 

420  GET  A*  :   IF  A$=""  THEN  420 

430  REM  ALL  DONE.  RESTORE  SVSTEM  TO  NORMAL 

440  REM  GIVE  BIT  MAP  MEMORV  BACK  TO  BASIC 

450  POKE  52,128   •'   POKE  56,128   :  CLR 

460  REM  POINT  VIC-II  AT  ORIGINAL  SCREEN  AND 

CHARACTER  MEMORV 
470  POKE  56576, (PEEK (56576)  AND  252)  OR  3 
480  REM  RETURN  TO  CHARACTER  MODE 
490  POKE  53265, PEEK(53265)  AND  223 
500  POKE  53272,21 
510  END 

520  REM  BIT  SETTING  SUBROUTINE 

530  PL  «  BM+(40*(V  AND  248))+(V  AND  7)+(X  AND  504) 
540  POKE  PL, PEEK (PL)  OR  M1XCX  AND  7) 
550  RETURN 
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One  important  difference  is  that  the  program  goes  into  a  loop  when  it's 
finished.  When  you  press  any  key,  it  will  return  to  the  "normal"  VIC-II 
segment.  When  using  bit-mapped  graphics,  you  must  do  this  in  your  pro- 
gram; you  can't  type  in  the  POKEs  to  do  it  from  the  keyboard,  because  the 
keyboard  and  display  only  work  in  character  display  mode. 

This  program  is  also  too  slow  for  lively  animation.  However,  in  the  next 
section  you  will  look  at  a  technique  for  smooth  player  movement  that  can  be 
used  in  BASIC. 

C-128  MODE  BIT-MAPPED 
GRAPHICS 

In  C-128  mode,  the  C-128  has  even  more  capabilities  than  it  does  in  C-64 
mode.  Additionally,  bit-mapped  graphics  in  C-128  mode  are  much  simpler  to 
program  because  of  the  powerful  BASIC  graphics  commands  that  are  a  part 
of  the  system. 

In  C-128  mode,  you  are  not  limited  to  bit-mapped  graphics,  because  the 
C-128  supports  split-screen  mode,  allowing  you  to  place  text  in  one  part  of  the 
screen  and  bit-mapped  graphics  in  thq  other. 

The  Graphics  Screens 

Instead  of  the  long  program  that  you  needed  to  enter  C-64  bit-mapped 
graphics,  C-128  mode  has  a  single  BASIC  command:  GRAPHIC.  There  are 
six  graphics  modes  available  in  C-128  mode:  40-column  text  only;  two-color 
bit-mapped  graphics;  two-color  split-screen;  multicolor  bit-mapped;  multi- 
color split-screen;  and  80-column  text  only  (used  only  with  an  RGB  display). 
The  basic  form  of  the  GRAPHIC  command  is 

GRAPHIC  m9  c 

where  m  is  the  mode  you  want  and  c  is  the  clear  byte.  If  c  is  l ,  GRAPHIC  will 
produce  a  blank  graphics  screen.  If  c  is  0,  the  screen  will  contain  either 
random  bytes  or  whatever  was  programmed  there  last.  For  example,  enter 
and  run  the  following  lines: 

10  GRAPHIC  1,0 

20  CIRCLE  1,160,130,60,40 

30  FOR  R=0  TO  2000:  NEXT 

50  GRAPHIC  0,0 

60  FOR  R=0  TO   1000:  NEXT 

70  GRAPHIC   1,  1 
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80  CIRCLE  1,170,120,50,30 
90  FOR  R=0  TO  2000:  NEXT 
100  GRAPHICS  0,0 

This  program  first  displays  and  draws  a  circle  on  the  bit-mapped  graph- 
ics screen  without  clearing  it  (this  may  be  a  bit  difficult  to  see  if  there  is  a  lot  of 
garbage  on  the  screen).  The  program  then  switches  to  text  mode  for  a  few 
seconds  and  back  to  the  graphics  screen  again.  During  this  time,  the  C-128 
clears  the  screen  first  and  then  draws  a  circle  before  returning  you  to  the  text 
screen. 


Bit-Mapped  Graphics  Shapes 

As  you  saw  in  the  last  example,  the  C-128  has  a  CIRCLE  command.  It  also 
has  a  number  of  other  bit-mapped  shape  commands.  You  will  look  at  each  of 
them  in  this  section. 


CIRCLE 

The  form  of  the  circle  command  is 

CIRCLE  c,  x,  y,  xr,  xr,  b,  e,  r,  s 

where  c  is  the  color  of  the  circle  (either  the  background  color,  the  foreground 
color,  or  one  of  the  two  multicolor  colors  in  multicolor  mode);  x  and  y  are  the 
coordinates  of  the  circle  (the  two-color  bit-mapped  screen  is  320X200);  xr 
and  xr  are  the  X  and  Y  radii,  b  and  e  are  beginning  and  ending  angles  for  an 
arc;  r  is  a  rotation  value;  and  s  indicates  the  length  of  the  sides  of  the  circle. 

NOTE:  The  default  side  length  is  1.  If  you  use  longer  lengths,  the 
CIRCLE  command  will  draw  regular  polygons  instead  of  circles.  Here  are 
some  examples  of  the  kinds  of  shapes  you  can  draw  with  CIRCLE. 

10  REM  GRAPHICS  DISPLAY 

20  GRAPHIC  1,1 

30  REM  CIRCLE 

40  CIRCLE  1,35,25,32,24 

50  CIRCLE  1, 120,25,32,24,,  ,30 

60  CIRCLE  1,200,25,32,24, ,, ,60 

70  CIRCLE  1,35,80,32,24, 72 

80  CIRCLE   1, 120,80,32,24, ,, ,90 

90  CIRCLE  1,200,80,32,24, ,,,  120 

100  CIRCLE  1,35,135,32,24,0,120 

By  changing  the  R  value,  you  can  make  a  shape  that  actually  spins  on  the 
screen. 
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10  GRAPHIC  1, 1 

20  FOR  G=0  TO  720  STEP  20 

30  GRAPHIC  1,1 

40  CIRCLE   1, 135,80,32,32, ,  ,G,  120 
50  NEXT 

60  FOR  R=0  TO  500:  NEXT 
70  GRAPHIC  O, 1 

POLYGONS 

As  you  can  see,  the  CIRCLE  command  will  draw  polygons  if  you  vary 
the  length  of  S.  To  calculate  the  S  values  for  a  particular  number  of  sides, 
divide  360  by  the  number  of  sides  you  want.  For  example,  to  draw  a  triangle, 
360/3=120,  so  you  enter  an  S  value  of  120. 

BOX 

The  form  of  the  BOX  command  is 

BOX  c,  xa,  ya,  xb,  yb,  r,f 

where  c  is  the  color  of  the  box  (background  color,  foreground  color,  or  one  of 
two  multicolor  colors  in  the  multicolor  mode);  xa  and  ya  locate  the  top-left 
cornerof  the  box;  xb  and  yb  locate  the  bottom-right  corner  of  the  box;  r  is  the 
rotation  value  of  the  box;  and / tells  the  C-128  whether  to  fill  the  box  with  the 
line  color  or  not.  For  example,  run  this  program  to  see  how  the  command 
works: 

10  GRAPHIC   1, 1 

20  BOX   1,55,35,95,65, , 1 

30  BOX  1,105,35,145,65 

40  FOR  R=OTO   lOOO:  NEXT 

50  GRAPHIC  O, 1 

DRAW 

The  DRAW  command  draws  a  straight  line  between  any  two  points  in 
the  graphics  screen.  The  form  of  a  DRAW  command  is 

DRAW  c,  xa,  ya  TO  xb,  yb 

where  c  is  the  color  (as  shown  earlier),  xa  andja  is  one  end  of  the  line,  and  xb 
and  yb  are  the  other  end  of  the  line.  Here  is  a  short  sample  program. 

lO  GRAPHIC  1, 1 
20  DRAW  1,10,10  TO  100,100 
30  FOR  G=0  TO  1000:  NEXT 
40  GRAPHIC  O, 1 
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Another  feature  of  DRAW  is  that  it  can  draw  multiple  lines  in  a  single 
command  by  simply  stringing  points  one  after  another,  as  shown  in  this 
program: 

10  GRAPHIC   1, 1 

20  DRAW   1,10,10  TO  100,100  TO  30, 70  TO   120,90  TO  250,12  TO  40,190  TO  1,9 
30  FOR  G=0  TO  1000:  NEXT 
40  GRAPHIC  O, 1 

To  draw  a  single  dot  on  the  screen,  use  DRAW  and  specify  only  one 
point. 

10  GRAPHIC  1,1 

20  DRAW   1, 10, 10 

30  DRAW  1, 1O0, 100 

40  DRAW  1,30,70 

50  DRAW  1, 120,90 

AO  DRAW  1,250,12 

70  DRAW  1,40, 190 

80  DRAW  1,1,9 

90  FOR  G=0  TO  lOOOs  NEXT 

lOO  GRAPHIC  0,1 


PAINT 

The  PAINT  command  fills  an  area  with  the  currently  specified  color. 
The  form  of  a  PAINT  command  is 

PAINT  c,  x,  y 

where  c  is  the  color  youH  be  painting,  and  x  and  y  are  a  point  inside  or  outside 
the  area  you  want  to  fill,  as  shown  here. 

10  GRAPHIC  1,1 

20  CIRCLE   1,120,140,50,50, ,,,120 

30  PAINT  1,120,140 

40  CIRCLE  1,120,140,50,50 

50  PAINT  1,1,1 

60  FOR  R=0  TO  2000: NEXT 

70  GRAPHIC  0,1 


SCALE 

The  SCALE  command  changes  the  values  of  the  screen  coordinates 
from  320  X  200  to  32767  X  32767.  This  gives  you  two  advantages.  First,  you 
do  not  have  to  compensate  for  the  distortion  of  the  tall,  rectangular  screen 
coordinates.  Second,  this  gives  a  much  larger  area  (numerically)  in  which  to 
plot.  The  form  of  the  SCALE  command  is 


scale  o 
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or 

SCALE  1 

where  SCALE  0  turns  scaling  OFF  and  SCALE  1  turns  scaling  ON.  The 
following  example  shows  two  hexagons  drawn  first  in  scaled  mode  and  then  in 
unsealed  mode. 

10  GRAPHIC  1,1: SCALE  1 

20  CIRCLE  1,88,99, 70, 80,  ,60 

30  SCALE  O:    CIRCLE  1 , 88, 99, 70, 80,  ,  , , 60 

40  FOR  R=0  TO  1000: NEXT 

50  GRAPHIC  O 

CHAR 

The  CHAR  command  allows  you  to  put  text  directly  in  the  graphics 
screen.  The  form  of  the  CHAR  command  is 

CHAR  c,  x,  y  "text" 

where  c  is  the  color  of  the  text,  x  and  y  are  its  starting  coordinates,  and  text  (in 
quotes)  is  the  text  you  want  printed.  Here  is  a  short  program  that  shows  the 
use  of  the  CHAR  command. 

10  graphic  1, 1 

20  CIRCLE   1,30,25,23,20,  ,,  ,60 
30  CHAR  1,8,3, "THIS   IS  A  HEXAGON" 
40  FOR  R=0  TO  1000:NEXT 
50  GRAPHIC  O 


C-64  MODE  SPRITE  GRAPHICS 

Using  custom  characters  to  animate  displays  has  a  drawback  in  some  cases: 
while  the  parts  of  a  player  can  be  moved  as  little  as  a  single  dot,  the  player  as  a 
whole  can  only  move  a  full  character  space  at  a  time.  You  could  get  around 
this  by  defining  different  versions  of  the  player  at  different  offsets  in  the  X  and 
Y  directions,  but  this  would  use  up  your  256  possible  custom  characters  very 
quickly.  There  is,  however,  an  easier  way  to  get  fine-tuned  player  movement  — 
by  using  sprites. 

A  sprite  is  a  special  form  of  player,  very  similar  to  the  ones  built  when 
using  custom  characters.  But  it  differs  in  one  very  important  way:  sprites  are 
completely  independent  of  the  rest  of  the  screen  display.  Sprites  can  overlap 
any  character  display  that  is  already  on  the  screen,  and  they  can  move  about 
without  affecting  it. 
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To  understand  how  sprites  work,  start  by  imagining  a  background 
displayed  on  a  transparent  sheet  of  glass: 


Although  you  could  also  put  players  made  of  built-in  or  custom  charac- 
ters on  this  display,  keep  things  simple  for  now  by  assuming  that  it's  all 
background.  Now,  on  a  second  sheet  of  glass,  you  will  draw  the  sprite,  an 
automobile: 
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Because  the  glass  is  transparent,  you  can  put  the  car  in  front  of  the 
background: 


Or  you  can  put  it  behind  the  background: 


aAa^A  — •  

v  v|piit  A  


vLl,   


You  can  also  move  the  glass  with  sprite  on  it,  while  leaving  the  back- 
ground fixed,  as  the  next  example  shows. 
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One  important  difference  between  sprites  and  the  other  types  of  players 
used  so  far  is  that  your  program  does  not  have  to  move  the  sprite  around  in 
memory  to  make  it  move  on  the  screen.  It  simply  tells  the  VIC-II  where  the 
sprite  belongs  on  the  screen  by  POKEing  its  position  into  certain  memory 
locations.  This  makes  sprites  much  easier  to  move. 

To  make  the  display  a  bit  livelier,  you  can  add  more  sheets  of  glass,  each 
with  its  own  sprite.  For  example,  you  could  add  some  trees  to  the  scene: 


You  can  arrange  these  sheets  so  that  the  car  passes  in  front  of  one  tree, 
but  behind  the  other  as  shown  next. 
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Through  all  this  action,  the  background  display  remains  unchanged, 
requiring  no  special  action  by  the  programmer  to  keep  track  of  what  should 
be  displayed  at  a  particular  location  on  the  screen.  The  VIC-II  chip  takes  care 
of  that  for  you. 

As  many  as  eight  sprites  can  appear  on  the  screen  at  any  given  moment, 
although  you  can  have  many  more  defined  in  memory  and  waiting  in  the 
wings.  You  may  find  it  helpful  to  think  of  the  screen  as  a  frame  that  can  hold 
up  to  eight  sheets  of  "sprite  glass"  at  once,  with  other  sheets  nearby,  ready  to 
be  switched  with  the  ones  already  in  place. 


Now  you  will  take  a  closer  look  at  how  sprites  work,  and  how  you  can 
paint  your  own  sprite  glass  and  get  it  into  the  frame. 
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HOW  SPRITES  ARE  DISPLAYED 

Sprites  are  displayed  on  the  screen  in  a  fashion  very  similar  to  ordinary 
characters.  As  discussed  earlier,  each  character  is  defined  by  a  table  in 
memory,  with  the  bits  in  each  memory  location  telling  the  VIC-II  chip  which 
dots  to  turn  on  and  which  to  turn  off.  Here,  once  again,  is  the  table  that  defines 
the  letter  "A." 


Displayed  Dots 


Binary 


00011000 
001 II 100 
01100110 
01111110 
01100110 
01100110 
01100110 
00000000 


Decimal 

24 

60 
102 
126 
102 
102 
102 
0 


The  table  for  a  sprite  is  very  similar.  The  difference  is  that  a  sprite  is 
bigger:  sprites  are  24  dots  wide  and  21  dots  high.  This  requires  a  bigger 
table:  a  sprite  table  is  3  bytes  wide  and  21  bytes  tall.  You  can  take  the  stick 
man  you  designed  earlier  in  this  chapter  and  turn  him  into  a  sprite. 
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Notice  the  empty  bytes  surrounding  the  stick  man.  These  must  be  there. 
The  size  of  a  sprite  is  fixed,  just  like  a  character,  and  the  empty  space  is  filled 
with  zeros.  This  makes  a  sprite  player  similar  to  a  player  made  up  of  several 
custom  characters.  You  may  find  it  helpful  to  think  of  a  sprite  as  an  oversized 
character. 


Sprite  Memory 

Sprite  definitions  are  stored  in  memory  just  like  character  definitions:  the 
top  row  first  (in  the  lowest  memory  locations),  followed  by  the  second  row, 
and  so  on  to  the  21st  row.  The  three  bytes  that  hold  the  24  dots  of  each  row  are 
next  to  each  other  in  memory.  If  the  definition  for  the  stick  man  sprite  were 
stored  starting  at  location  32768,  it  would  look  like  this: 

32768  0  ) 

32769  28  >      top  row 

32770  96  ) 

32771  0  ) 

32772  62  /      second  row 

32773  96  ) 

32774  0  ) 

32775  62  >      third  row 

32776  96  ) 


32825 

32826  102  ;>      20th  row 

32827 

32828 

32829  102  >      21st  row 

32830 


This  arrangement  in  memory  does  differ  from  that  of  a  similar  player 
made  of  custom  characters.  However,  the  values  in  the  table  bytes  are  the 
same,  so  a  custom  character  player  can  be  converted  to  a  sprite  with  just  a 
little  work.  The  design  tools  and  techniques  are  also  quite  similar.  You  will 
examine  those  a  little  later  in  this  chapter. 

One  difference  between  sprite  memory  and  the  other  areas  you've  looked 
at  is  that  there  is  no  specific  block  of  memory  reserved  for  sprites.  The 
characters  displayed  on  the  screen  and  the  character  definition  tables  are 
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grouped  together  in  their  own  areas  of  computer  memory.  While  you  can 
change  the  starting  location  of  the  screen  or  character  memory  areas,  you 
can't  split  them  up.  You  can't,  for  example,  put  the  definitions  of  the  first  128 
characters  in  locations  32768-33791,  and  the  second  128  in  locations 
34816-35839. 

This  sort  of  restriction  does  not  apply  to  sprites.  For  each  sprite,  the 
VIC-II  chip  has  a  separate  pointer  to  the  memory  locations  that  contain  the 
sprite's  definition.  So,  while  all  the  bytes  for  each  sprite's  definition  have  to  be 
together,  the  various  sprites  can  be  scattered  all  over  the  VIC-II's  16K  segment 
of  memory. 

The  ability  to  store  sprite  definitions  throughout  the  segment  is  the  secret 
to  keeping  sprites  available.  These  sprites  can  be  used  not  only  to  expand  your 
"cast  of  characters,"  but  to  animate  them,  too.  You  will  examine  the  tech- 
niques for  using  them  a  little  later. 

DESIGNING  SPRITES 

Since  a  sprite  is  so  much  like  a  custom  character  player,  you  might  expect 
the  design  processes  to  be  very  similar,  and  indeed  they  are.  Begin  with  a 
design  form,  just  as  you  did  for  custom  characters.  Start  with  the  long  edge  of 
your  graph  paper  running  horizontally,  and  draw  a  box  24  squares  wide  and 
21  squares  tall,  so  that  it  looks  like  this: 
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You  should  position  the  box  so  that  it  is  toward  the  left  edge  of  the  paper. 
This  leaves  room  on  the  right  side  for  any  calculations  that  you  may  need  to 
make.  Now  divide  the  box  into  three  columns  of  eight  squares,  and  number 
the  columns  like  this: 


1  l  l 

2631  2631  2631 

8426842     1842684218426842  1 


As  in  the  custom  character  design  form,  each  box  corresponds  to  a  dot 
on  the  screen.  The  three  columns  correspond  to  bytes  in  sprite  memory. 

In  practice,  the  sprite  design  form  works  just  like  the  custom  character 
form.  Here  is  the  stick  man  again,  designed  as  a  sprite. 
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o 

28 

96 

o 

62 

96 

o 

62 

96 

o 

62 

96 

o 

62 

96 

o 

28 

96 

o 

62 

96 

l 

255 

224 

3 

255 

0 

6 

255 

0 

6 

255 

0 

6 

255 

0 

6 

255 

0 

6 

255 

0 

0 

126 

0 

0 

102 

0 

0 

102 

0 

0 

I02 

0 

0 

102 

0 

0 

102 

0 

0 

23! 

0 

The  binary  values  have  been  left  out  in  this  example.  As  you  get  more 
practice  in  converting  the  dots  to  numbers,  you  will  probably  want  to  do  the 
same.  Also,  all  the  zeros  were  put  in  for  the  "empty"  bytes.  This  is  a  good  habit 
to  develop,  since  it  is  easy  to  forget  them  otherwise. 

If  you  have  written  or  purchased  programs  to  help  design  players  made 
of  custom  characters,  they  can  also  be  used  for  sprites.  Just  remember  that  the 
bytes  are  stored  in  a  different  order  in  sprite  memory. 

Now  you  will  take  a  look  at  the  programming  techniques  for  using 
sprites. 

PUTTING  YOUR  SPRITE  TO  WORK 

Once  you  have  designed  a  sprite,  there  are  several  programming  steps 
necessary  to  make  it  work. 

1 .  Reserve  memory  for  your  sprite  definition. 

2.  Load  the  sprite  definition  into  memory. 

3.  Tell  the  VIC-II  where  the  sprite  definition  is. 

4.  Tell  the  VIC-II  to  start  displaying  your  sprite. 

5.  Move  the  sprite  onto  the  screen. 
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This  may  sound  like  a  lot  of  work,  but  each  of  these  steps  is  actually  quite 
simple.  In  the  sections  that  follow,  each  step  will  be  examined  in  turn. 


Loading  Your  Sprite  Definition 
Into  Memory 

Just  as  with  custom  characters,  the  first  steps  in  a  program  using  sprites  are  to 
reserve  the  memory  needed  for  the  definitions,  and  then  to  load  them  into  that 
memory.  This  program  loads  the  stick  man  sprite  into  memory. 

100  REM  RESERVE  MEMORV 
110  CLR:P0KE  52, 128: POKE  56, 128 : CLR 
120  REM  MOVE  SCREEN  TO  HIGH  MEMORV 
130  POKE  648,132 

140  POKE  56576, <PEEK<56576)flND  252)  OR  1 
150  PRINT 

160  REM  LORD  SPRITE 

170  FOR  1*32832  TO  32894   :   READ  X   :   POKE  I,X   :  NEXT 

180  REM  SPRITE  DRTR,  2  RONS  PER  STATEMENT 

190  DRTR  0,28,96,  0,62,96 

200  DRTR  0,62,96,  0,62,96 

210  DRTR  0,62,96,  0,28,96 

220  DRTR  0,62,96,  0,255,96 

230  DRTR  3,255,192,  6,255,0 

240  DRTR  6,255,0,  6,255,0 

250  DRTR  6,255,0,  6,255,0 

260  DRTR  0,126,0,  0,102,0 

270  DRTR  0, 102,0,         0, 102,0 

280  DRTR  0, 102,0,         0, 102,0 

290  DRTR  0,231,0 

The  program  is  very  similar  to  the  one  used  to  set  up  the  custom 
character  player.  As  before,  the  first  line  of  the  program  resets  the  limits  of 
memory  and  does  a  CLR  to  reset  BASIC'S  internal  memory  pointers.  The 
program  then  POKEs  the  locations  in  the  CIA  (complex  interface  adapter) 
chip  that  controls  the  VIC-II's  "segment"  of  memory  and  BASIC'S  pointer  to 
screen  memory.  Finally,  the  program  uses  a  READ  loop  to  load  the  sprite 
definition  into  memory. 


Telling  the  VIC-II  Chip 
Where  to  Find  Your  Sprite 

Now  that  the  sprite  definition  is  in  memory,  the  VIC-II  chip  must  be  told 
where  to  find  it.  As  with  screen  and  character  memory,  there  are  "pointers"  to 
tell  the  VIC-II  where  in  its  16K  segment  the  sprite  definitions  reside.  Sprite 
memory  pointers  are  also  incomplete:  some  of  the  bits  come  from  memory, 
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and  some  are  calculated  by  the  VIC-II  chip.  Instead  of  supplying  only  three  or 
four  bits  of  the  location,  sprite  definition  pointers  supply  eight  of  them: 


13 

12 

11 

10 

9 

8 

7 

6 

2  10 


Calculated  by  VIC-II 
From  sprite  memory  pointer 


The  formula  for  calculating  the  POKE  value  has  to  change,  too.  The 
following  BASIC  statement  will  do  this: 

100  PV-SDfl/64  AND  255 

The  result  of  the  calculation,  PV,  will  be  assigned  the  numeric  value  of 
the  8  bits  to  be  supplied  to  the  VIC-II.  You  divide  SDA  (the  Sprite  Definition 
Address)  by  64  because  6  bits  of  the  location  number  are  calculated  by  the 
VIC-II,  and  64  is  2  to  the  6th  power.  The  division  eliminates  those  calculated 
bits.  The  AND  operation  is  used  to  eliminate  bits  from  the  left.  Remember 
that  there  are  16  bits  in  the  number  that  identifies  a  memory  location  (0- 
65535)  but  only  14  bits  in  a  number  that  identifies  a  location  in  the  VIC-II's 
16K  segment.  Since  a  byte  can  only  hold  8  bits,  you  have  to  get  rid  of  the 
others.  The  AND  makes  sure  that  only  values  0  through  255  will  be  POKEd. 
The  two  bits  that  select  the  right  16K  segment  are  the  ones  you  POKEd  into 
the  CIA  chip,  so  you  don't  have  to  worry  about  them  being  lost. 

Look  at  this  formula  in  action.  You  started  the  definition  for  the  stick 
man  sprite  at  location  32832.  Watch  what  happens  to  the  bits  as  the  calcula- 
tion progresses. 

1000000001000000  32832 

/64 


513 
AND 
255 


0000000000000001  1 


0000001000000001 
0000000011111111 


The  correct  value  to  POKE  is  1.  What  would  have  happened  if  you  had 
decided  to  start  sprite  definition  at  location  32833?  The  binary  value  of  32833 
is  1000000001000001.  The  last  bit  would  be  lost  in  the  calculation,  so  the 
VIC-II  would  think  that  the  definition  started  at  location  32832.  This  would 
give  a  strange-looking  player,  because  the  last  8  dots  on  each  row  would  be 
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shifted  onto  the  next  row.  The  fact  that  the  VIC-II  calculates  the  last  6  bits  of 
the  address  limits  the  locations  where  a  sprite  definition  can  begin  in  memory. 


Now  that  you  know  what  value  to  POKE,  you  need  to  know  where  it  goes. 
As  mentioned  before,  computers  are  binary  creatures,  like  numbers  that  are 
powers  of  2.  So  even  though  there  are  only  1000  visible  locations  in  screen 
memory,  the  VIC-II  perceives  screen  memory  as  being  an  area  of  1024  bytes. 
The  sprite  definition  pointers  are  stored  in  some  of  the  wasted  24  bytes,  so  the 
map  of  screen  memory  really  looks  like  this: 


0 
64 
128 
192 
256 
320 


16192 
16256 
16320 


Offset 


Contents 


0 


Row  0,  column  0 
Row  0,  column  1 
Row  0,  column  2 
Row  0,  column  3 


2 
3 


997 
998 
999 
1000 
1001 


Row  24,  column 
Row  24,  column 
Row  24,  column 
Not  used 


Not  used 


37 
38 
39 


1014 
1015 
1016 


Not  used 
Not  used 
Sprite  pointer  0 
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1U1  / 

Sprite  pointer  1 

1  A  1  O 

1018 

iSpnte  pointer  2 

1019 

Sprite  pointer  3 

1020 

Sprite  pointer  4 

1021 

Sprite  pointer  5 

1022 

Sprite  pointer  6 

1023 

Sprite  pointer  7 

In  the  examples,  you  are  using  the  segment  that  starts  at  location  32768, 
with  screen  memory  starting  at  location  33792,  so  the  sprite  pointers  start  at 
location  34808.  To  make  the  stick  man  sprite  0,  the  correct  POKE  location  is 
34808.  The  segment  to  tell  the  VIC-II  chip  about  the  sprite  definition  is 

100  POKE  34808. 1 

Type  in  and  execute  this  statement  now.  Nothing  will  change  on  the 
screen  yet,  because  you  still  have  a  few  steps  to  go  before  the  sprite  can  make 
its  entrance. 


Enabling  and  Disabling  Sprites 

Every  location  on  the  character  display  must  contain  something.  Even  if  you 
want  nothing  to  appear,  you  must  display  a  blank.  This  is  not  the  case  with 
sprites.  They  must  be  enabled  (turned  ON)  and  disabled  (turned  OFF)  by  your 
program.  Although  this  requires  an  extra  program  step,  it  does  have  some 
advantages.  For  example,  it  means  you  don't  have  to  define  a  blank  sprite  if 
you  don't  plan  to  use  all  eight  at  the  same  time.  More  important,  though,  is 
that  you  can  build  up  your  sprite  without  having  it  appear  on  the  screen  before 
it's  finished. 

Sprites  are  enabled  and  disabled  by  bits  in  location  53269,  which  is  part 
of  the  VIC-II  chip. 


Bit  number 


7 

6 

5 

4 

3 

2 

1 

0 

Sprite  affected 

 Sprite  0 

—  Sprite  1 

—  Sprite  2 
 Sprite  3 

—  Sprite  4 

—  Sprite  5 

 Sprite  6 

 Sprite  7 
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If  the  bit  that  controls  a  sprite  is  ON  (has  a  value  of  l ),  the  sprite  is  enabled  and 
appears  on  the  screen.  If  the  bit  is  OFF,  the  sprite  is  disabled.  To  turn  the  bit 
for  a  particular  sprite  OFF  or  ON  without  disturbing  the  others,  use  AND  and 
OR  for  bit-masking,  as  described  earlier.  For  example,  to  enable  sprite  l ,  you 
could  use  the  statement 

100  POKE  53269 j  PEEK (53269)  OR  2 

Remember  that  you  must  PEEK  the  value  that  is  already  in  the  byte,  so  you 
will  have  the  values  of  the  other  bits  to  POKE  back  into  it.  To  disable  a  sprite, 
use  AND  to  turn  its  bit  OFF.  The  statement 

100  POKE  53269 , PEEK ( 53269  >  AND  254 

will  disable  sprite  0,  making  it  disappear  from  the  screen.  The  statement 
above  also  PEEKs  first  to  preserve  the  values  of  the  other  bits.  Here  are  the 
masks  to  use  for  enabling  and  disabling  sprites. 

Sprite  To  enable,        To  disable, 

Number  OR  with  AND  with 


0 

1 

254 

1 

2 

253 

2 

4 

251 

3 

8 

247 

4 

16 

239 

5 

32 

223 

6 

64 

191 

7 

128 

127 

Now  enable  the  sample  sprite  by  entering  the  statement 
POKE  53269, PEEK < 53269)  OR  1 

Once  again,  nothing  happens  to  the  screen.  The  sprite  is  actually  being 
displayed,  but  it  is  behind  the  border,  and  now  you  have  to  tell  the  VIC-II  to 
move  it  onto  the  screen. 

Moving  Your  Sprite 

From  the  discussion  so  far,  you've  probably  guessed  that  sprite  positions  are 
expressed  in  dots,  and  that  dots,  like  character  rows  and  columns,  are 
numbered  from  the  upper-left  corner  to  the  lower-right  corner.  But  there  is 
one  thing  about  sprite  positioning  that  may  surprise  you:  the  numbering  does 


232     C-128  USER  GUIDE 


not  start  in  the  visible  area  of  the  screen.  The  lowest-numbered  dot  is  actually 
in  the  border  area! 

While  this  may  seem  strange  at  first,  there  is  a  good  reason  for  it.  Most  of 
the  time,  you  will  not  want  your  sprite  to  suddenly  appear  on  the  screen.  Like 
an  actor  in  a  play,  your  sprite  will  usually  make  an  entrance,  moving  onto  the 
screen  from  behind  the  border.  You  can't  do  this  unless  you  have  some  way  to 
position  the  sprite  in  the  border  area,  so  the  numbering  of  the  dots  actually 
starts  off  screen.  The  numbering  looks  like  this: 


To  avoid  confusion  with  screen  character  positions,  the  dot  counts  will  be 
referred  to  as  the  "X-position"  for  left-to-right  and  the  "Y-position"  for 
top-to-bottom,  rather  than  as  "row"  and  "column." 


Sprite  X-position  Y-position 

Number  Location  Location 

0  53248  53249 

1  53250  53251 

2  53252  53253 

3  53254  53255 

4  53256  53257 

5  53258  53259 

6  53260  53261 

7  53262  53263 
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To  get  the  sample  sprite  (sprite  0)  onto  the  screen,  enter  these  statements: 

POKE  53248, 100 
POKE  53249,100 

Try  a  few  more  POKEs  into  these  locations,  and  watch  what  happens  to  the 
position  of  the  sprite.  In  particular,  try  POKEing  a  value  of  255  into  location 
53248,  the  sprite's  X-position. 

As  you  experimented  with  moving  the  sprite,  you  may  have  noticed  that 
you  couldn't  get  it  near  the  right-hand  edge  of  the  screen.  Look  back  at  the 
drawing  that  shows  the  X-and  Y-positioning  values  to  see  why.  An  X-position 
value  of  255  (the  largest  number  you  can  POKE  into  a  byte)  will  only  move  a 
sprite  about  three-fourths  of  the  way  across  the  screen.  To  move  the  rest  of  the 
way,  you  need  a  9-bit  number,  which  can  contain  values  from  0  to  511. 

Since  a  byte  can  only  hold  eight  bits,  the  VIC-II  must  get  the  ninth  bit 
from  some  other  location.  Eight  extra  bits  are  needed  (1  for  each  sprite),  so 
Commodore  grouped  them  together  in  one  location  in  the  VIC-II.  These  bits 
are  in  the  same  order  as  the  enable  bits,  allowing  you  to  use  the  same  bit  masks 
used  to  enable  or  disable  the  sprite.  To  see  how  this  is  done,  look  at  a  complete 
subroutine  that  will  position  a  sprite  on  the  screen.  This  subroutine  is  given 
three  variables. 

SN    The  "Sprite  Number"  (0  through  7) 
XP    The  X-position  of  the  sprite 
YP    The  Y-position  of  the  sprite 

Such  a  subroutine  might  look  like  this: 

10000  XL  «  53248  +  2  *  SN 

10010  VL  »  XL  +  1 

10020  IF  XP  >  255  THEN  10050 

10030  B9  a  PEEK (53264)  AND  NOT  C21SH') 

10040  GOTO  10060 

10050  B9  «  PEEK (53264)  OR  <21SN) 

10060  XV  =  XP  AND  255 

10070  POKE  XL j XV   :   POKE  VL,VP   :  POKE  53264 ,B9 

This  subroutine  probably  seems  a  bit  obscure.  Here  is  a  line-by-line  review. 

10000     Calculates  the  memory  location  to  POKE  for  the  X-position. 

10010     Calculates  the  memory  location  to  POKE  for  the  Y-position. 

10020  Different  masking  operations  must  be  done,  depending  on  the 
value  of  the  ninth  bit  in  the  X-position.  If  XP  is  less  than  256, 
the  ninth  bit  is  a  0. 


234     C-1 28  USER  GUIDE 


10030     "B9"  is  set  to  the  new  value  for  the  bit  9  location  in  the  VIC-II. 

The  exponentiation  gives  a  mask  in  which  only  the  bit  for  the 
chosen  sprite  is  a  1.  The  PEEK  gets  the  current  value,  and  the 
OR  turns  on  the  bit. 

10040  The  GOTO  skips  over  the  processing  for  an  X-position  that  is 
less  than  256. 

10050  If  the  ninth  bit  is  a  0,  you  must  force  off  the  sprite's  bit  in  the  bit 
9  location.  By  using  a  NOT,  you  generate  a  mask  in  which  the 
sprite's  bit  is  a  0  and  all  others  are  1  's.  The  AND  forces  the  bit  off. 

10060  The  AND  with  255  makes  sure  that  you  don't  try  to  POKE  too 
big  a  number  into  the  X-position  location. 

10070  This  line  POKEs  the  position  information  into  the  VIC-II 
chip's  locations. 

The  last  line  of  this  subroutine  is  important.  It  is  usually  not  a  good 
programming  practice  to  combine  statements  on  one  line,  because  it  makes 
programs  harder  to  read.  One  exception  already  mentioned  is  a  short  FOR- 
NEXT  loop,  such  as  the  delay  loops  used  for  animation,  where  putting 
everything  on  one  line  makes  the  program  easier  to  follow.  In  this  subroutine 
the  POKEs  are  combined  into  one  line  for  a  different  reason:  it  takes  time  to 
do  the  calculations  for  the  POKE  values.  If  you  calculated  and  POKEd  each 
value  separately,  it  could  make  the  motion  of  the  sprite  a  little  choppy.  This  is 
especially  true  when  the  X-position  goes  from  255  to  256.  If  you  POKEd  the 
X-position  location  and  then  calculated  the  bit  9  location  value,  the  sprite 
would  jump  off  the  screen  while  you  were  doing  the  calculation  and  then  jump 
back  on  when  you  POKEd  the  bit  9  value.  Depending  on  the  order  in  which 
the  calculations  and  POKEs  are  done,  this  might  cause  a  noticeable  flicker. 
While  you  don't  have  to  follow  the  order  of  calculations  used,  you  will  find 
that  you  get  the  most  pleasing  results  by  doing  the  calculations  first,  and  then 
the  POKEs. 

Animating  Sprites 

Like  custom  character  players,  sprites  can  be  animated  by  defining  different 
versions  and  changing  the  version  displayed  "on  the  fly."  There  is  one 
difference,  though:  while  you  can  redefine  part  of  a  custom  character  player, 
you  must  define  a  completely  new  sprite  for  each  position  in  the  animation 
sequence.  In  the  section  on  custom  character  players,  you  animated  the  stick 
man  by  making  him  wave.  Here's  a  C-64  mode  program  that  does  the  same 
thing  with  the  sprite  stick  man. 
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900  REM  RESERVE  MEMORV 
1000  CLR:PQKE  52, 128= POKE  56,128:CLR 
1010  REM  MOVE  SCREEN  TO  HIGH  MEMORV 
1020  POKE  648,132 

1030  POKE  56576, (PEEK < 56576) AND  252)  OR  1 

1040  PR I NT "n" 

1100  REM  LORD  SPRITE  1 

1200  FOR  1=32832  TO  32894  :  READ  X  :  POKE  I,X  ■*  NEXT 
1300  REM  SPRITE  DATA,  2  RONS  PER  STATEMENT 

1400  DATA  0,28,96,  0,62,96 

1401  DRTR  0,62,96,  0,62,96 

1402  DRTR  0,62,96,  0,28,96 

1403  DRTR  0,62,96,  0,255,96 

1404  DRTR  3,255,192,  6,255,0 

1405  DRTR  6,255,0,  6,255,0 

1406  DRTR  6,255,0,  6,255,0 

1407  DRTR  0,126,0,  0,102,0 

1408  DRTR  0,102,0,  0,102,0 

1409  DRTR  0,102,0,  0,102,0 

1410  DRTR  0,231,0 
2100  REM  LORD  SPRITE  2 

2200  FOR  1*32896  TO  32958  :  RERD  X  :  POKE  I,X  :  NEXT 
2300  REM  SPRITE  DRTR,  2  ROWS  PER  STATEMENT 

2400  DRTR  0,28,0,  0,62,0 

2401  DRTR  0,62,3,  0,62,6 

2402  DRTR  0,62,12,  0,28,24 

2403  DRTR  0,62,48,  0,255,224 

2404  DRTR  3,255,192,  6,255,0 

2405  DRTR  6,255,0,  6,255,0 

2406  DRTR  6,255,0,  6,255,0 

2407  DRTR  0,126,0,  0,102,0 

2408  DRTR  0,102,0,  0,102,0 

2409  DRTR  0,102,0,  0,102,0 

2410  DRTR  0,231,0 
3100  REM  LORD  SPRITE  3 

3200  FOR  1=32960  TO  33022  :  READ  X  :  POKE  I,X  :  NEXT 
3300  REM  SPRITE  DRTR,  2  ROWS  PER  STATEMENT 

3400  DATA  0,28,0,  0,62,0 

3401  DATA  0,62,0,  0,62,0 

3402  DATA  0,62,0,  0,28,0 

3403  DATA  0,62,255,  0,255,255 

3404  DATA  3,255,192,  6,255,0 

3405  DATA  6,255,0,  6,255,0 

3406  DATA  6,255,0,  6,255,0 

3407  DATA  0,126,0,  0,102,0 

3408  DATA  0,102,0,  0,102,0 

3409  DATA  0,102,0,  0,102,0 

3410  DATA  0,231,0 

4100  REM  ENABLE  THE  SPRITE 

4110  POKE  34808, 1 

4120  POKE  53269, PEEK (53269)  OR  1 

4200  REM  PUT  IT  ON  THE  SCREEN 

4210  POKE  53248, 100 

4220  POKE  53249, 100 

4300  REM  START  MAKING  IT  MOVE 
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4310 

POKE  34808.2 

4320 

FOR  I  »  1  TO 

250 

NEXT 

4330 

POKE  34808,3 

4340 

FOR  I  *  1  TO 

250 

NEXT 

4350 

POKE  34808,2 

4360 

FOR  I  «  1  TO 

250 

NEXT 

4370 

POKE  34808,1 

4380 

FOR  I  »  1  TO 

250 

NEXT 

4390 

GOTO  4300 

Here  is  the  C-128  mode  version  of  the  same  program. 


10  PRINT  CHR*(147) 

20  FOR    1=3584  TO  3646:    READ  X:    POKE   I,  X:  NEXT 

30  DATA  0,28,96,0,62,96,0,62,96,0,62,96,0,62,96,0,28,96,0,62,96,0,255,96,3,255 
40  DATA   192,6,255,0,6,255,0,6,255,0,6,255,0,6,255,0,0,  126,  O,  O,  102,  O,  O,  102,  O,  O 
50  DATA  102,0,0,102,0,0,102,0,0,231,0 
60  FOR    1=3648  TO  3710:    READ  X:    POKE   I, X: NEXT 

70  DATA  0,28,0,0,62,0,0,62,3,0,62,6,0,62,  12,0,28,24,0,62,48,0,255,224,3,255 
80  DATA   192,6,255,0,6,255,0,6,255,0,6,255,0,6,255,0,0,  126,  O,  O,  102,  O,  O,  102,  O,  O 
90  DATA  102,0,0,102,0,0,102,0,0,231,0 
100  FOR   1=3712  TO  3774:   READ  X:   POKE   I,  X:  NEXT 

110  DATA  0,28,0,0,62,0,0,62,0,0,62,0,0,62,0,0,28,0,0,62,255,0,255,255,3,255 

120  DATA   192,6,255,0,6,255,0,6,255,0,6,255,0,6,255,0,0, 126,0,0, 102,0,0, 102,0,0 

130  DATA  102,0,0,102,0,0,102,0,0,231,0 

1 35  MOVSPR   1 , 1 00 , 1 00 

140  SPRITE  1,1,2,0,1,1,0 

150  POKE  216,255 

160  FOR  R=56  TO  58 

170  POKE    (2040) ,R 

180  FOR  G=0  TO   100: NEXT 

190  NEXT 

200  FOR  R=57  TO  56  STEP  -1 

210  POKE    (2040) ,R 

220  FOR  G=0  TO   100: NEXT 

230  NEXT 

240  GOTO  160 


Lines  4300  through  4380  are  the  key  to  the  animation:  you  POKE 
location  34808,  which  is  the  sprite  definition  pointer  for  sprite  0.  No  matter 
how  much  of  the  sprite  changes,  only  one  POKE  is  necessary.  If  the  player's 
movements  must  be  complex  —  as  in  a  figure  that  walks  and  waves  at  the  same 
time  —  it  is  much  easier  to  animate  a  sprite  than  a  custom  character  player. 
There  is  a  price  for  this,  though;  the  sprite  method  will  usually  require  more 
memory.  In  most  cases,  this  will  not  be  a  problem,  but  it  is  something  you 
must  keep  in  mind  when  designing  programs. 

To  liven  up  the  display  a  bit  more,  add  these  lines  to  the  program: 

4222  XP*100:VP*100:SN=100 
4224  XI=3:VI=3 

4300  REM  STRRT  MAKING  IT  MOVE 

4310  POKE  34808,2 

4320  GOSUE  4400 

4330  POKE  34808,3 

4340  G03UB  4400 

4350  POKE  34808,2 
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4360  GOSIJB  4400 
4370  POKE  34808, 1 
4380  GOSUB  4400 
4390  GOTO  4300 
4400  FOR  1*1  TO  5 
4410  XP=XP+XI 
4420  VP-VP+VI 
4430  GOSUB  10000 

4440  IF  XP<21  OR  XP>320  THEN  XI— XI 
4450  IF  VP<51  OR  VP  >228  THEN  VI=-VI 
4460  FOR  J*l  TO  25 : NEXT 
4470  NEXT  I 
4480  RETURN 

10000  XL  a  53248  +  2  *  SN 

10010  VL  ■  XL  +  1 

10020  IF  XP  >  255  THEN  10050 

10030  E9  «=  PEEK  C  53264)  AND  NOT  <2tSN> 

10040  GOTO  10060 

10050  B9  *  PEEK (53264)  OR  <2fSN) 

10060  XV  *  XP  AND  255 

10070  POKE  XL , XV   :  POKE  VL.VP   :  POKE  53264, B9 


When  you  RUN  the  program,  the  stick  man  will  start  to  wave  again,  but 
this  time  he  drifts  around  the  screen  at  the  same  time.  When  he  hits  the 
border,  he  bounces  off  it  and  heads  off  in  a  different  direction. 

You  will  use  modified  versions  of  this  program  to  illustrate  other  sprite 
concepts.  SAVE  a  copy  of  it  to  reduce  wear  and  tear  on  your  typing  fingers. 

In  the  C-128  version  of  this  routine,  the  man  simply  travels  from  left  to 
right,  disappears  at  the  right,  and  reappears  at  the  left. 


10  PRINT  CHR*<147> 

20  FOR   1=3584  TO  3646:    READ  X:    POKE   I, X: NEXT 

30  DATA  0,28,96,0,62,96,0,62,96,0,62,96,0,62,96,0,28,96,0,62,96,0,255,96,3,255 
40  DATA   192,6,255,0,6,255,0,6,255,0,6,255,0,6,255,0,0, 126, 0,0, 102, 0,0, 102, 0,0 
50  DATA  102,0,0,102,0,0,102,0,0,231,0 
60  FOR   1=3648  TO  3710:    READ  X:    POKE   I, X: NEXT 

70  DATA  0,28,0,0,62,0,0,62,3,0,62,6,0,62,  12,0,28,24,0,62,48,0,255,224,3,255 
80  DATA   192,6,255,0,6,255,0,6,255,0,6,255,0,6,255,0,0,  126 , O, 0 , 102 , 0 , 0 ,  102 , 0 , O 
90  DATA  102,0,0,102,0,0,102,0,0,231,0 
100  FOR   1=3712  TO  3774:    READ  X:    POKE   I, X: NEXT 

110  DATA  0,28,0,0,62,0,0,62,0,0,62,0,0,62,0,0,28,0,0,62,255,0,255,255,3,255 

120  DATA   192,6,255,0,6,255,0,6,255,0,6,255,0,6,255,0,0, 126, 0,0, 102,0,0, 102,0,0 

130  DATA  102,0,0,102,0,0,102,0,0,231,0 

140  MOVSPR   1 ,20, 100 

150  MOVSPR   1,90  #5 

160  SPRITE  1,1,2,0,1,1,0 

170  POKE  216,255 

180  FOR  R=56  TO  58 

190  POKE    (2040) ,R 

200  FOR  G=0  TO   100: NEXT 

210  NEXT 

220  FOR  R=57  TO  56  STEP  -1 

230  POKE    (2040) ,R 

240  FOR  G=0  TO   100: NEXT 

250  NEXT 

260  GOTO  180 
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C-128  MODE  SPRITE  GRAPHICS 

As  you  can  see  from  the  last  section,  there  is  quite  a  bit  of  programming 
necessary  to  create  a  sprite  in  C-64  mode.  This  same  process  will  work  in 
C-128  mode  as  well,  but  you  don't  need  to  go  to  all  that  trouble  if  you  are 
programming  in  C-128  mode  because  there  are  several  sprite  commands  that 
make  the  process  of  programming  a  sprite  simple. 

Designing  a  Sprite 

The  easiest  way  to  design  a  sprite  is  with  the  new  SPRDEF  (sprite  definition) 
utility.  To  design  a  sprite  this  way,  type  the  command  SPRDEF  and  press 
RETURN.  This  will  display  a  large  rectangle  that  fills  more  than  half  the 
screen.  This  is  the  sprite  editing  area.  When  it  is  first  displayed,  the  sprite 
editing  area  will  be  gray  and  you  will  see  the  words  SPRITE  NUMBER  below 
it.  Before  you  can  begin  designing  your  sprite,  you  must  select  one  of  the  sprite 
numbers  (1  through  8),  This  will  erase  the  gray  background,  read  the  selected 
sprite  pattern  into  the  editing  area,  and  reveal  the  sprite  editing  cursor  (a 
small  +  sign). 

MOVING  AROUND  IN  THE  SPRITE  EDITOR 

Moving  the  cursor  around  in  the  sprite  editing  window  is  similar  to 
moving  the  cursor  around  the  normal  text  screen.  The  cursor  control  keys 
move  the  cursor  up,  down,  left,  and  right  (both  the  C-64  style  cursor  control 
keys  at  the  bottom  of  the  keyboard  and  the  CP/  M  type  cursor  control  keys  at 
the  top  of  the  keyboard.) 

The  CLR  HOME  key  works  much  as  it  does  in  BASIC.  If  you  press  the  key 
by  itself,  the  cursor  will  jump  back  up  to  the  top  of  the  window.  Pressing  the 
SHIFT  key  and  CLR  HOME  together  clears  the  sprite  and  returns  the  cursor  to 
the  top  of  the  window. 

The  RETURN  key  moves  the  cursor  down  a  row  and  over  to  the  far  left 
side  of  the  row,  just  as  it  does  in  BASIC. 

When  you  first  enter  the  sprite  editor,  the  cursor  will  automatically  move 
to  the  right  each  time  you  select  a  color  block  (press  1 , 2, 3,  or  4).  If  you  do  not 
want  the  cursor  to  move  automatically  to  the  next  position  after  each  block, 
press  the  A  key  on  the  keyboard. 

EDITING  THE  SPRITE 

Sprites  can  be  displayed  in  two  modes:  standard  two-color  mode  and 
multicolor  (four-color)  mode.  In  two-color  mode,  the  1  and  2  keys  at  the  top 
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of  the  keyboard  and  in  the  numeric  keypad  toggle  the  block  under  the  cursor 
between  the  foreground  color  (2)  and  the  background  color  (1). 

In  multicolor  mode,  the  1 , 2, 3,  and  4  keys  select  between  the  background 
color  (1);  foreground  color  (2);  multicolor  #1  (3);  and  multicolor  #2  (4). 

NOTE:  In  multicolor  mode,  blocks  are  colored  two  at  a  time  because 
multicolor  sprites  have  half  the  resolution  of  two-color  sprites.  To  select 
multicolor  mode,  press  the  M  key  on  the  keyboard. 

To  select  different  foreground  colors,  press  the  CTRL  key  and  one  of  the 
number  keys  for  colors  1-8;  then  press  the  Commodore  key  (lower  left-hand 
corner  of  the  keyboard)  and  one  of  the  number  keys  for  colors  9-16. 

BELLS  AND  WHISTLES 

Pressing  the  X  key  will  toggle  the  sprite  between  horizontal  expanded 
mode  and  horizontal  nonexpanded  mode.  Pressing  the  Y  key  will  toggle  the 
sprite  between  vertical  expanded  mode  and  vertical  nonexpanded  mode. 

To  copy  the  pattern  from  one  sprite  to  another,  select  the  sprite  that  you 
want  to  copy  to  and  press  the  C  key.  The  C-128  will  ask  you  which  sprite  you 
want  to  copy  from.  Press  the  number  of  the  master  sprite  and  its  pattern  will 
be  copied  onto  the  currently  selected  sprite. 

ENDING  THE  EDIT 

To  end  a  sprite  session,  you  have  two  options.  If  you  want  to  save  the 
pattern  you  created,  press  the  SHIFT  key  and  RETURN  key  at  the  same  time.  If 
you  want  to  exit  without  saving  your  work,  press  the  RUN/  STOP  key.  In  either 
case,  you  will  be  prompted  for  a  sprite  number  again.  If  you  want  to  leave  the 
editor,  press  RETURN. 

SAVING  SPRITE  DEFINITIONS 

To  save  your  sprite  definitions  on  disk,  enter  the  following  line: 

10  BSAVE   " SPRITES", BO, P3584  TO  P4096 

You  can  use  any  name  less  than  16  characters  long  in  place  of  the  file  name, 
SPRITES.  To  read  the  sprites  back  again,  enter  this  line: 

10  BLOAD  "SPRITES" 

Coloring  Sprites 

Just  as  each  location  in  screen  memory  has  a  corresponding  location  in  color 
memory,  each  sprite  has  a  location  that  contains  its  color.  Sprite  colors  are 
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stored  in  the  VIC-II  chip,  not  in  memory.  The  memory  locations  that  control 
sprite  colors  are  shown  here. 

Location       Sprite  number 

53287  0 

53288  1 

53289  2 

53290  3 

53291  4 

53292  5 

53293  6 

53294  7 

These  locations  take  the  same  POKE  values  that  color  memory  loca- 
tions do. 

To  see  sprite  colors  in  action  in  the  C-64  mode  version  of  the  program, 

change  the  sprite  demonstration  program  so  it  looks  like  this: 

188  REM  RESERVE  MEMORV 
118  CLR:P0KE  52, 128= POKE  56, 128 : CLR 
128  REM  MOVE  SCREEN  TO  HIGH  MEMORV 
138  POKE  648,132 

148  POKE  56576, < PEEK (56576) AND  252 >  OR  1 

150  PR I NT "n" 

168  REM  LORD  SPRITE  1 

178  FOR  1=32832  TO  32894  :   READ  X   =   POKE  I,X  :  NEXT 

188  REM  SPRITE  DATA,  2  ROUS  PER  STATEMENT 

198  DATA  8,28,96,  8,62,96 

288  DATA  8,62,96,  8,62,96 

218  DATA  8,62,96,  8,28,96 

228  DATA  8,62,96,  0,255,96 

230  DATA  3,255,192,  6,255,0 

240  DATA  6,255,8,  6,255,0 

258  DATA  6,255,0,  6,255,0 

260  DATA  0,126,0,  0,102,0 

270  DATA  0,182,0,  0,102,0 

280  DATA  0,102,8,  8,102,0 

290  DATA  8,231,0 

300  REM  LOAD  SPRITE  2 

310  FOR  1=32896  TO  32958   =   READ  X   :   POKE  I,X   :  NEXT 

320  REM  SPRITE  DATA,  2  ROWS  PER  STATEMENT 

330  DATA  0,28,0,  0,62,0 

340  DATA  0,62,3,  0,62,6 

350  DATA  0,62,12,  0,28,24 

360  DATA  0,62,48,  0,255,224 

370  DATA  3,255,192,  6,255,0 

388  DATA  6,255,8,  6,255,8 

398  DATFI  6,255,8,  6,255,8 

400  DATA  0,126,0,  0,102,0 

410  DATA  8,102,8,  0,102,0 
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420  DATA  0,102,0,  0,102,0 

430  DATA  0,231,0 

440  REM  LORD  SPRITE  3 

450  FOR  1=32960  TO  33022  :  RERD  X   :   POKE  I,X   :  NEXT 

460  REM  SPRITE  DRTR,  2  ROWS  PER  STATEMENT 

470  DRTR  0,28,0,  0,62,0 

480  DRTR  0,62,0,  0,62,0 

490  DRTR  0,62,0,  0,28,0 

500  DRTR  0,62,255,  0,255,255 

510  DRTR  3,255,192,  6,255,0 

520  DRTR  6,255,0,  6,255,0 

530  DRTR  6,255,0,  6,255,0 

540  DRTR  0, 126,0,        0, 102,0 

550  DRTR  0,102,0',  0,102,0 

560  DRTR  0,102,0,  0,102,0 

570  DRTR  0,231,0 

580  REM  ENABLE  THE  SPRITE 

590  POKE  34808, 1 

600  POKE  53269 ,  PEEK  (.  53269  >  OR  1 

610  REM  PUT  IT  ON  THE  SCREEN 

620  SN=0 

630  XP=100   :   XI  =  1 

640  VP= 100   :    VI  =  1 

650  GOSUB  10000 

660  REM  STRRT  MAKING  IT  MOVE 

670  POKE  34808,2 

680  GOSUB  760 

690  POKE  34808,3 

700  GOSUB  760 

710  POKE  34808,2 

720  GOSUB  760 

730  POKE  34808,1 

740  GOSUB  760 

750  GOTO  660 

760  FOR  I  =  1  TO  5 

770  XP  »  XP+XI 

780  VP  «  VP+VI 

790  GOSUB  10000 

800  IF  XP<21  OR  XP  >  320  THEN  XI  *  -XI   =  GOSUB  860 
810  IF  VP<51  OR  VP  >  228  THEN  VI  =  -VI    :  GOSUB  860 
820  REM  FOR  J  =  1  TO  25  NEXT 
830  NEXT  I 
840  RETURN 

850  REM  MAKE  HIM  "BLUSH" 

860  POKE  53287,10 

870  FOR  J  =  1  TO  250   :  NEXT 

880  POKE  53287,1 

890  RETURN 

10000  XL  »  53248  +  2  #  SN 

10010  VL  a  XL  +  1 

10020  IF  XP  >  255  THEN  10050 

10030  B9  «=  PEEK < 53264)  AND  HOT  <2tSN> 

10040  GOTO  10060 

10050  B9  =  PEEK < 53264)  OR  (2tSN) 
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10060  XV  *  XP  AND  255 

10070  POKE  XL j  XV   :   POKE  VL,VP   :    POKE  53264, B9 
10080  RETURN 

Now  RUN  the  program  and  watch  the  results.  Each  time  the  man  bumps 
into  the  wall,  he  turns  red  for  a  moment  before  continuing. 

In  the  C-128  mode  version  of  this  routine,  the  man  changes  colors  as  he 
travels  across  the  screen. 


10  PRINT  CHR*<147) 

20  FOR   1=3584  TO  3646:    READ   X:    POKE   I, X: NEXT 

30  DATA   0,28,  96,  0,62,  96,  0,62,96,0,  62,  96,  0,62,  96,  0,28,  96,  0,62,  96,  0,255,  96,  3,  255 
40  DATA   192,6,255,0,6,255,0,6,255,0,6,255,0,6,255,0,0, 126,0,0, 102,0,0, 102,0,0 
50  DATA  102,0,0,102,0,0,102,0,0,231,0 
60  FOR   1=3648  TO  3710:    READ   X:    POKE   I, X: NEXT 

70  DATA   O,  28,  O,  O,  62,0, O, 62, 3, O, 62, 6,  O,  62,  12,0,  28,  24,  O, 62, 48, O, 255, 224, 3, 255 
80  DATA   192,6,255,0,6,255,0,6,255,0,6,255,0,6,255,0,0, 126,0,0, 102,0,0, 102,0,0 
90  DATA  102,0,0,102,0,0,102,0,0,231,0 
100  FOR   1=3712  TO  3774:    READ  X:    POKE   I, X: NEXT 

110  DATA  O, 28, O, 0,62, O, O, 62,  O,  O,  62,  O,  O,  62,  O,  O,  28,  O,  O, 62, 255, O, 255, 255, 3, 255 

120  DATA   192, 6, 255, 0, 6, 255, O, 6,  255, O,  6,  255 , 0 , 6 , 255 , 0 , 0 ,  126, O, O,  102, O, O,  102, O, O 

130  DATA  102,0,0,102,0,0,102,0,0,231,0 

140  MOVSPR  1,20,100 

150  MOVSPR    1,90  #5 

160  SPRITE  1,1,2,0,1,1,0 

170  POKE  216,255 

180  FOR  R=56  TO  58 

190  POKE    (2040) ,R 

195  SPRITE    1 ,  1 , R-48, O,  1  ,  1 ,  O 

200  FOR  G=0  TO   100: NEXT 

210  NEXT 

220  FOR  R=57  TO  56  STEP  -1 

230  POKE    ( 2040 ) , R 

235  SPRITE    1,  l,R-50,0,  1,  1,0 

240  FOR  G=0  TO   100: NEXT 

250  NEXT 

260  GOTO  180 


Sprite  Interaction 

When  sprites  move  around  on  the  screen,  they  sometimes  overlap  each  other 
or  objects  in  the  background  display.  The  sprite  world  is  like  the  real  world  in 
that  two  objects  can't  occupy  the  same  space  at  the  same  time.  Only  one  object 
can  be  displayed  in  a  particular  dot  position  at  any  one  moment.  The  VIC-II 
has  a  set  of  rules  to  determine  which  object  gets  priority  when  two  or  more 
compete  for  a  particular  dot.  It  also  has  a  way  to  tell  your  program  when  two 
objects  collide.  In  this  section  you  will  look  at  those  rules  and  at  how  you  can 
use  them  in  your  programs. 


DISPLAY  PRIORITIES 

In  the  introduction  to  sprites,  they  were  described  as  figures  on  sheets  of 
glass.  Each  sheet  can  hold  only  one  sprite,  so  when  two  sprites  try  to  occupy 
the  same  position,  one  must  pass  "behind"  the  other.  The  rule  for  determining 
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which  one  gets  priority  (passes  "in  front")  is  very  simple:  sprite  0  is  always  in 
front  of  sprite  1 ,  which  is  in  front  of  sprite  2,  and  so  on.  Sprite  7,  of  course,  will 
pass  behind  any  other  sprite.  To  see  this  in  action  in  C-64  mode,  type  in  and 
RUN  the  following  program: 


100  REM  RESERVE  MEMORV 
110  CLR:POKE  52, 128  =  POKE  56,128:CLR 
120  REM  MOVE  SCREEN  TO  HIGH  MEMORY 
130  POKE  648, 132 

140  POKE  56576 j  (PEEK (56576) AND  252)  OR  1 
150  PR  I  NT" IT' 

160  REM  LORD  SPRITE  0  (DIAMOND) 
170  FOR  1=32832  TO  32894  =  READ  X 


POKE  I,X  •  NEXT 


2  ROWS  PER  STATEMENT 
0,0.0 


180  REM  SPRITE  DATA, 
190  DATA  0,0,0, 
200  DATA  0,0,0, 
210  DATA  0,24,0, 
220  DATA  0, 126,0, 
230  DATA  1,255.128, 
240  DATA  7,255,224, 
250  DATA  3,255, 192, 
260  DATA  0,255,0, 
270  DATA  0,60,0, 
280  DATA  0,0,0, 
290  DATA  0,0,0 

300  REM  LOAD  SPRITE  1  (SQUARE) 
310  FOR  1=32896  TO  32958  :  POKE  1,255 
320  REM  ENABLE  THE  SPRITES 
330  POKE  34808, 1 
340  POKE  34809,2 
350  POKE  53269, PEEKC53269)  OR  3 
360  PFM  PUT  THEM  ON  THE  SCREEN 
XI(0)=3 
XI(1)*~3 


0,0,0 
0,60,0 
0,255,0 
3,255, 192 
7,255,224 
1,255, 128 
0, 126,8 
0,24,0 
0,0,0 


NEXT 


370  X<0>*50 

380  X(l)=50 
390  VP=150 
400  FOR  SH«C 


GOSUB  10000   :  NEXT 


TO  1    :  XP*X(SN) 
410  REM  START  MAKING  THEM  MOVE 
420  FOR  SN  =  0  TO  1 
430  X(SN)  =  X(SN)+XI(8N) 
440  XP*X(SN) 

450  IF  X(SNK21  OR  X<SN»  75    THEN  XI  (SN)  ■  -XKSN) 

460  GOSUB  10000 

470  REM  FOR  J  =  1  TO  25  :  NEXT 

480  NEXT 

490  GOTO  410 

10000  XL  ■  53248  +  2  *  SN 

10010  VL  ~  XL  +  1 

10020  IF  XP  >  '255  THEN  10050 

10030  B9  *  PEEK (53264)  AND  NOT  (2tSN) 

10040  GOTO  10060 


10050  B9  = 


10060  XV  ~ 
10070  POKE  XL, XV 
10080  RETURN 


PEEK (53264) 
XP  AND  255 


OR  (2'TSN) 


POKE  VL,VP  :  POKE  53264, B9 
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The  C-128  mode  version  of  the  program  looks  like  this: 


10  PRINT  CHR*(147) 

20  FOR   1=3584  TO  3646:   READ  X:    POKE   I,  X:  NEXT 

30  DATA  0,0,0,0,0,0,0,0,0,0,0,0,0,24,0,0,60,0,0,  126,0,0,255,0,  1,255,  128,3,255 

40  DATA   192,7,255,224,7,255,224,3,255,  192,  1,255, 128,0,255,0,0,  126,0,0,60,0,0,24 

50  DATA  0,0,0,0,0,0,0,0,0,0 

60  FOR   1=3648  TO  3710:   POKE   I, 255: NEXT 

150  SPRITE  2,1,3,1,1,1,0 

160  SPRITE  1,1,2,1,1,1,0 

170  MOVSPR  1,100,100 

180  MOVSPR  2,100,100 

190  MOVSPR   1,270  #5 

200  MOVSPR  2,90  #5 


When  the  program  is  executed,  it  creates  two  simple  sprites  and  moves  them 
back  and  forth  across  the  screen.  The  diamond  shape  is  sprite  0  and  always 
passes  in  front  of  the  square.  Notice  that  the  "transparent"  part  of  the 
diamond  doesn't  blot  out  the  square;  only  the  "visible"  part  covers  up  any  of 
the  dots  that  make  up  the  square.  Now  interrupt  the  program  and  enter  these 
lines  for  C-64  mode: 

330  POKE  34888,2 
340  POKE  34809,1 

and  these  for  C-128  mode: 

100  POKE  216,255 
110  POKE  2040,  56 
120  POKE  2041,  57 

The  POKEs  switched  the  sprites,  so  that  the  square  became  sprite  0  and  the 
diamond  sprite  1.  Now  the  diamond  passes  behind  the  square.  Notice  that  it 
makes  no  difference  where  the  sprite  is  in  memory;  the  only  thing  that  counts 
is  which  sprite  definition  pointer  points  to  it. 

The  relationships  between  sprites  are  only  half  the  story,  though.  Sprites 
can  also  pass  either  in  front  of  or  behind  the  background  display.  To  illustrate 
this,  add  the  following  lines  to  the  C-64  mode  program: 

355  REM  PUT  SQURRE  BEHIND  BACKGROUND 

356  POKE  53275 j  PEEK (53275)  OR  2 

Or  add  these  lines  to  the  C-128  mode  program: 

160  SPRITE  1,1,4,0,1,1,0 

210  PS*=CHR*<147>  :FOR  R=0  TO  7:  PS*=PS*+CHR*  ( 17)  :  NEXT 
220  PRINT  PS*; "THIS  TEXT  IS  BETWEEN  THE  SPRITES" 

When  you  RUN  the  program,  youll  see  that  the  square  (sprite  1)  passes 
behind  the  background,  but  the  diamond  (sprite  0)  passes  in  front  of  both  the 
square  and  the  background  display.  The  secret  to  this  is  the  POKE  in  line  356, 
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which  clears  a  bit  that  tells  the  VIC-II  that  sprite  1  has  a  higher  priority  than 
the  background.  Like  many  of  the  other  bits  that  control  sprites,  there  are 
eight  of  them,  one  per  sprite,  grouped  together  in  one  location,  number 
53275.  The  least  significant  bit  controls  sprite  0,  and  the  most  significant  bit 
controls  sprite  7. 


Sprite  affected 

—  Sprite  0 

—  Sprite  1 

—  Sprite  2 
— Sprite  3 

—  Sprite  4 

—  Sprite  5 

—  Sprite  6 

—  Sprite  7 

If  a  sprite's  bit  in  this  location  is  a  0,  it  takes  priority  over  the  background  and 
passes  in  front  of  it.  If  the  bit  is  a  1,  the  sprite  passes  behind  the  background. 
The  bits  are,  of  course,  controlled  with  bit-masking  operations.  As  always,  in 
C-64  mode  you  must  PEEK  location  53275  first,  to  save  the  values  of  the 
other  bits.  To  put  sprite  3  behind  the  background  in  C-64  mode,  you  would 
use  a  statement  like 

100  POKE  53275  >  PEEK  < 53275  )  OR  8 

However,  C-128  mode  allows  you  to  use  the  simple  BASIC  command 
SPRITE  to  control  all  of  the  sprite  attributes.  The  form  of  the  SPRITE 
command  is 

SPRITE  n,  v,  c,  p,  ex,  ey,  m 

where  n  is  the  sprite  number  (1-9);  v  is  the  visible  bit  (1  is  ON  and  0  is  OFF);  c  is 
the  sprite  color;  p  is  the  priority  (whether  it  is  in  front  of  or  behind  the 
background);  ex  and  ey  are  the  expansion  bits  that  make  it  twice  as  wide  (ex) 
or  twice  as  tall  (ey);  and  m  determines  whether  the  sprite  is  multicolor  or 
two-color  (1  is  multicolor,  0  is  two-color).  The  C-128  mode  command  to  put 
sprite  3  behind  the  background  would  be 

10  SPRITE  3,1,3,1,1,1,0 

To  put  sprite  7  in  front  of  the  background  in  C-64  mode,  use 

100  POKE  53275, PEEK < 53275)  AND  127 
In  C-128  mode,  choose  the  priority  bit  (p)  from  1  to  0. 


Bit  number 
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Splitting  the  sprite-to-sprite  priorities  from  the  sprite-to-background 
priorities  has  an  interesting  side  effect.  Change  line  356  of  the  C-64  mode 
program  to 

356  POKE  53275,1 

or  line  150  of  the  C-128  mode  program  to 

150  SPRITE  2,1,3,0,1,1,0 

Now  RUN  the  program  and  watch  what  happens.  The  square  (sprite  1)  is 
in  front  of  the  background,  and  the  diamond  (sprite  0)  is  behind  it.  But  the 
diamond  passes  in  front  of  the  square,  because  sprite  0  always  has  priority 
over  sprite  1 .  So,  when  the  diamond  and  the  square  overlap,  the  background 
is  in  front  of  the  part  of  the  square  that  is  covered  by  the  diamond!  This  makes 
perfect  sense  as  far  as  the  VIC-II's  priority  rules  are  concerned,  but  don't 
spend  too  much  time  trying  to  imagine  how  this  works  with  the  "sheets  of 
glass." 

Detecting  Collisions 
In  C-64  Mode 

In  the  real  world,  when  two  cars  collide,  the  results  are  noisy  and  messy. 
Fortunately,  things  are  not  that  bad  in  the  sprite  world.  Instead,  the  VIC-II 
simply  sets  some  flags  to  let  you  known  who  hit  whom. 

Being  able  to  detect  collisions  is  very  handy  for  game  software.  The 
process  of  finding  overlaps  by  calculation  uses  up  a  lot  of  computer  time  and 
slows  down  the  action.  However,  collision  detection  is  also  useful  for  almost 
any  program  that  uses  sprites  to  simulate  moving  objects. 

There  are  two  different  types  of  collisions.  One  occurs  when  two  sprites 
overlap,  and  the  other  is  a  result  of  a  sprite  passing  in  front  of  or  behind  an 
object  in  the  background  display.  Each  type  of  collision  is  recorded  in  its  own 
location:  location  53279  marks  collisions  between  sprites  and  the  back- 
ground, and  location  53278  contains  bits  to  identify  sprites  that  collide  with 
each  other.  Like  many  of  the  other  locations  in  the  VIC-II,  each  location 
contains  one  bit  for  each  sprite,  with  the  least  significant  bit  corresponding  to 
sprite  0  and  the  most  significant  bit  to  sprite  7.  This  allows  you  to  use  the  same 
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bit  masks  for  examining  these  locations  that  are  used  to  set  bits  in  the 
"controlling"  locations. 

Here  is  how  collision  detection  works  in  a  program.  This  example  uses 
the  diamond  and  square  sprites  from  the  earlier  example,  but  this  time  they 
don't  pass  each  other:  when  they  touch,  they  bounce  and  reverse  direction. 
There  are  also  added  "walls"  in  the  background  that  the  sprites  bounce  off 
when  they  touch. 


100  REM  RESERVE  MEMORV 
110  CLR:POKE  52, 128  '•  POKE  56,  128  :  CLR 
120  REM  MOVE  SCREEN  TO  HIGH  MEMORV 
130  POKE  648,132 

140  POKE  56576, (PEEK (56576) AND  252)  OR  1 
150  PR  I  NT  "IT 

160  REM  LORD  SPRITE  0  (DIAMOND) 

170  FOR  1=32832  TO  32894   :  READ  X   =   POKE  I,X   :  NEXT 

180  REM  SPRITE  DATA,  2  ROWS  PER  STATEMENT 

190  DATA  0,0,0,  0,0,0 

200  DATA  0,0,0,  0,0,0 

210  DATA  0,24,0,  0,60,0 

220  DATA  0,126,0,  0,255,0 

230  DATA  1,255,128,  3,255,192 

240  DATA  7,255,224,  7,255,224 

250  DATA  3,255,192,  1,255,128 

260  DATA  0,255,0,  0,126,0 

270  DATA  0,60,0,  0,24,0 

280  DATA  0,0,0,  0,0,0 

290  DATA  0,0,0 

300  REM  LOAD  SPRITE  1  (SQUARE) 

310  FOR  1=32896  TO  32958  :  POKE  1,255   :  NEXT 

320  REM  BUILD  THE  WALLS 

330  FOR  I  =  1  TO  8  :  PRINT  :  NEXT 

340  FOR  I  «  1  TO  10  :  PRINT"*  »"    :  NEXT 

350  REM  ENABLE  THE  SPRITES 

360  POKE  34808,1 

370  POKE  34809,2 

380  POKE  53269, PEEK (53269)  OR  3 

390  REM  PUT  THEM  ON  THE  SCREEN 

400  X(0)*60   :  XI(0)=2 

410  X(l)«35   :  XI(1)=-1 

420  VP«150 

430  FOR  SN«0  TO  1    :   XF'=X(SN)    :  GOSUB  10000  :  NEXT 
440  REM  START  MAKING  THEM  MOVE 
450  FOR  SN  =  0  TO  1 
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460  X(SN)  *  X(SN)+XI(SN) 

470  XP*X(SN) 

480  GOSUE  10000 

490  REM  CHECK  FOR  COLLISION  WITH  OTHER  SPRITE 

500  IF  PEEK (53278)  -  0  THEN  GOTO  600 

510  REM  IMPACT!  REVERSE  COURSE 

520  xi <e>  =  -xi (0)  •  xi a )  =  -xi a > 

530  REM  BRCK  UP  THE  SPRITE  WE  JUST  MOVED 
540  X(SN)  »  X<SN)  +  XKSN)  *  2 
550  XP=X(SN) 
560  GOSUE  10900 

570  REM  CLEAR  THE  SPRITE  COLLISION  FLAGS 
530  Ml  ■  PEEK (53278) 

590  REM  CHECK  FOR  COLLISION  WITH  BACKGROUND 
600  IF  (PEEK (53279)  AND  2tSN)  =  0  THEN  GOTO  690 
610  REM  HIT  THE  WALL!  REVERSE  COURSE 
620  XI  (SN)  =  -XKSN) 

630  REM  BACK  UP  THE  SPRITE  WE  JUST  MOVED 
640  X(SN)  =  X(SN)  +  XKSN) 
650  XP*X(SN) 
660  GOSUE  10000 

670  REM  CLEAR  THE  BACKGROUND  COLLISION  FLAG 
680  DD  =  PEEK (53279) 
690  NEXT 
700  GOTO  440 

10000  XL  a  53248  +  2  *  SN 

10010  VL  ~  XL  +  1 

10020  IF  XP  >  255  THEN  10050 

10030  E9  *  PEEK (53264)  AND  NOT  <21SN> 

18040  GOTO  10060  . 

10050  B9  »  PEEK (53264)  OR  <21SN) 

10060  XV  *  XP  AND  255 

10070  POKE  XL, XV   :   POKE  VL,VP   :   POKE  53264, B9 
10080  RETURN 

Most  of  this  program  should  be  familiar  by  now,  so  the  review  concentrates 
on  the  parts  that  use  collision  detection. 

Line  500  PEEKs  location  53278,  which  contains  the  flags  for  sprite-to- 
sprite  collisions.  In  this  example,  you  are  using  only  two  sprites,  so  any 
nonzero  value  means  that  the  two  have  collided.  A  more  complex  program 
involving  many  sprites  would  use  bit-masking  to  determine  which  two  sprites 
had  collided.  To  detect  a  collision  between  sprites  3  and  5,  you  can  use  this 
statement: 

100  IF  PEEK (53278)  AND  40  =  40  THEN  GOTO  200 

Where  did  the  40  come  from?  The  mask  value  for  sprite  3  is  8,  and  sprite  5's  is 
32.  By  adding  8  and  32,  you  get  a  mask  that  will  force  off  all  bits  except  those 
for  sprites  3  and  5.  The  comparison  to  40  is  important,  too;  it  makes  sure  that 
both  bits  are  on.  If  sprite  3  had  collided  with  sprite  2,  the  PEEK  value  would 
be  12  (8  plus  4).  If  12  and  40  are  ANDed  together,  the  result  is  8.  This  value  is 
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not  zero,  so  a  simple  IF  would  see  a  true  result.  By  comparing  the  result  of  the 
AND  to  40,  you  know  whether  both  sprites  or  just  one  of  them  was  involved 
in  the  collision. 

Your  program  should  check  the  collision  flags  after  every  sprite  move.  If 
it  doesn't,  it  may  be  difficult  to  determine  exactly  who  hit  whom.  For 
example,  if  sprites  2  and  3  are  colliding  in  the  upper-left  corner  of  the  screen, 
and  sprites  0  and  4  are  colliding  at  the  same  time  in  the  lower-right  corner,  a 
PEEK  into  location  53278  will  return  a  value  of  15,  because  all  four  are 
involved  in  collisions.  In  order  to  figure  out  which  sprites  are  touching  which, 
your  program  must  resort  to  the  calculations  that  the  collision  detection 
mechanism  is  designed  to  eliminate.  Checking  after  each  move  avoids  this 
extra  work. 

Line  580  demonstrates  another  important  characteristic  of  the  collision 
flags.  The  REM  statement  in  line  570  says  that  you  are  clearing  the  flags,  but 
you  would  expect  that  to  be  done  with  a  POKE,  not  a  PEEK.  The  reason  lies 
in  the  electronic  design  of  the  VIC-II  chip.  Whenever  a  sprite  is  involved  in  a 
collision,  its  collision  flag  bit  is  set.  The  bit  stays  set  until  the  collision  flag 
location  is  examined  with  a  PEEK  (there  are  certain  advantages  to  designing 
chips  this  way,  and  the  practice  is  quite  common).  If  the  flag  is  cleared  by 
PEEKing,  why  do  you  have  to  PEEK  again  to  clear  it?  As  soon  as  you  cleared 
the  flags  with  the  first  PEEK,  the  VIC-II  discovered  that  the  sprites  were  still 
colliding,  so  it  set  them  again  (it  checks  every  time  it  scans  the  display).  To 
clear  the  flags,  you  had  to  move  the  sprite  and  then  PEEK  again.  If  the  flags 
weren't  cleared,  you  would  get  a  false  indication.  Even  though  the  two  sprites 
were  no  longer  touching,  the  VIC-II  hadn't  communicated  to  the  program 
and  would  remember  the  collision  until  it  had.  Try  deleting  line  580  from  the 
program,  and  watch  what  happens.  The  program  thinks  that  the  two  sprites 
are  colliding  all  the  time,  so  once  they  touch,  they  sit  there  and  vibrate, 
reversing  every  move. 

Although  this  section  hasn't  mentioned  the  sprite-to-background  colli- 
sion flags,  their  electronic  design  is  the  same  as  the  sprite-to-sprite  flags. 
YouH  need  to  use  the  same  methods  to  clear  them  and  to  avoid  false 
collisions. 

DETECTING  COLLISIONS 
IN  C-128  MODE 

As  you  have  probably  guessed  by  now,  C-128  mode  collision  detection 
involves  a  simple  BASIC  command.  It's  called  COLLISION.  The  following  is 
the  basis  form  of  COLLISION. 
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COLLISION  k,  In 

where  k  is  the  kind  of  collision  you  want  to  detect  and  In  is  a  program  line 
number.  The  options  for  k  are  1  for  sprite-to-sprite  collisions,  2  for  sprite-to- 
background  collisions,  and  3  for  light-pen  detection,  which  isn't  covered  here. 

To  give  you  an  example  of  how  these  work,  study  sprite-to-background 
collisions.  In  the  following  example,  you  draw  a  couple  of  barriers  (one  each 
at  the  left  and  right  sides  of  the  screen).  Then  you  create  a  simple  sprite  and 
start  it  traveling  across  the  screen.  When  it  bumps  into  a  barrier,  the  COLLI- 
SION command  detects  it  and  reverses  the  sprite  direction. 

lO  PRINT  CHR*<147) : A=l : BK*=CHR* < 166)  :S*=CHR*(19> 
15  FOR  G=0  TO  5:    S*=S*+CHR* ( 17 ) : NEXT 
20  FOR  1=3584  TO  3646:   POKE  I, 255: NEXT 
30  SPRITE  1,1,2,1,0,0,0 
40  MOVSPR  1,100,100 
50  MOVSPR   1,270  #3 
60  PRINT  S*;BK*;BK*;" 
70  PRINT  BK*;BK*;" 
BO  PRINT  BK*; BK*; " 
90  COLLISION  2, 110 
100  GOTO  90 
110  COLLISION  2 
120   IF  A=l   THEN  GOTO  150 
130  MOVSPR   1,-7,  +0 

140  MOVSPR   1,270  #3:    A=A*-1:G0T0  160 
150  MOVSPR   1, +7, +0: MOVSPR  1,90  #3:A=A*-1 
160  RETURN 

Line  10  clears  the  screen  and  the  direction  variable,  A.  Lines  20  through 
50  create  the  sprite  and  start  it  moving.  Lines  60  through  80  draw  the  walls 
and  line  90  looks  for  a  collision.  Line  100  keeps  sending  the  program  back  to 
90  if  it  hasn't  spotted  a  collision.  If  a  collisions  is  detected,  then  line  110  clears 
the  collision  register  and  line  120  detects  the  current  sprite  direction  (by 
looking  at  the  value  of  A).  Then  lines  130  and  150  move  the  sprite  out  of  the 
collision  area  and  start  the  sprite  going  in  the  opposite  direction.  Finally,  line 
160  returns  control  to  the  COLLISION  statement  in  line  90. 


" ; BK*; BK* 
" ; BK*; BK* 
" ; BK*; BK* 


CHAPTER 

Sound 


This  chapter  will  show  you  how  to  produce  sound  with  the  C-128.  You  will 
learn  how  to  create  convincing  sound  effects  to  enhance  your  programs. 

You  will  also  learn  how  to  control  the  sound  registers,  mix  tones,  and  use 
sound-shaping  techniques  to  produce  variations  such  as  tremolo  and  vibrato. 

In  addition  to  showing  you  how  to  produce  sounds,  this  chapter  explains 
how  to  save  and  play  back  your  sound  effects  from  either  the  disk  drive  or  the 
Datassette. 

All  of  the  techniques  and  programs  in  the  first  part  of  this  chapter  will 
work  in  both  C-64  and  C-128  modes.  The  second  part  of  the  chapter  will  take 
a  look  at  some  special  features  available  only  in  C-128  mode. 

The  SID  Chip 

Like  the  video  display,  the  sounds  that  the  C-128  makes  are  created  by  a 
special  integrated  circuit.  This  chip  is  called  the  Sound  Interface  Device,  or 
SID.  The  SID  contains  three  separate  sound  generators,  or  "voices,"  that  are 
blended  together  to  form  the  sound  you  hear  through  your  TV  speaker. 

The  SID  has  25  memory  locations,  called  sound  registers,  that  control 
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sound  output.  These  locations  control  the  volume,  the  tone,  and  the  type  of 
sounds  produced.  Table  7-1  shows  the  memory  location  and  function  of  each 
of  the  sound  registers. 

Memory  location  54296  controls  the  volume  of  the  sounds.  Sixteen 
different  volume  levels  can  be  selected.  These  range  from  0  (off)  to  15 
(loudest).  To  control  the  volume,  enter  any  value  between  1  and  15.  By  itself, 
however,  the  volume  control  register  does  not  produce  sound.  You  must  also 
set  the  voice  control  registers. 


TABLE  7-1.  Sound  Register  Memory  Locations 


Memory  Location 

Sound  Register  Description 

54272  -  54278  VOICE  #1 

54272 

Lower  half  of  tone  frequency  value 

54273 

Upper  half  of  tone  frequency  value 

54274 

Lower  half  of  pulse-width  value 

54275 

Upper  half  of  pulse-width  value 

54276 

Waveform  control  register 

54277 

Attack  and  Decay  control  register 

54278 

Sustain  and  Release  control  register 

54279  -  54285  VOICE  #2 

54279 

Lower  half  of  tone  frequency  value 

54280 

Upper  half  of  tone  frequency  value 

5428 1 

Lower  half  of  pulse-width  value 

54282 

Upper  half  of  pulse-width  value 

54283 

Waveform  control  register 

54284 

Attack  and  Decay  control  register 

54285 

Sustain  and  Release  control  register 

54286  -  54292  VOICE  #3 

54286 

Lower  half  of  tone  frequency  value 

54287 

Upper  half  of  tone  frequency  value 

54288 

Lower  half  of  pulse-width  value 

54289 

Upper  half  of  pulse-width  value 

54290 

Waveform  control  register 

5429 1 

Attack  and  Decay  control  register 

54292 

Sustain  and  Release  control  register 

54293  -  54296  SOUND  FILTERING  FUNCTIONS 

54293 

Lower  half  of  cutoff  filter  value 

54294 

Upper  half  of  cutoff  filter  value 

54295 

Resonance  and  sound  filtering  values 

54296 

Mode  and  volume  controls 
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Voice  Control  Registers 

Looking  at  Table  7-1,  you'll  notice  that  each  of  the  three  "voices,"  or  voice 
control  registers,  is  associated  with  a  set  of  seven  memory  locations.  These 
locations  control  the  type  of  sound  produced  by  that  voice.  All  three  sets  of 
voice  control  registers  work  the  same  way;  so  even  though  most  of  the 
examples  use  voice #  1 ,  you  can  use  the  same  values  to  POKE  notes  into  voices 
#2  and  #3. 


SETTING  UP  THE  VOICE 
CONTROL  REGISTERS 

When  the  C-128  is  turned  ON,  the  voice  control  registers  take  on  random 
values.  If  the  registers  are  not  POKEd  with  the  right  values,  the  SID  will 


TABLE  7-2.  POKE  Values,  Frequencies  and  Musical  Equivalents 


Upper  Tone 

Lower  Tone 

Frequency 

Musical 

POKE  Value 

POKE  Value 

Produced 

Note 

OCTAVE  ONE 

12 

16  Hz 

C 

28 

17  Hz 

C# 

45 

18  Hz 

D 

62 

19  Hz 

D# 

81 

21  Hz 

E 

101 

22  Hz 

F 

123 

23  Hz 

F# 

145 

24  Hz 

G 

169 

25  Hz 

G# 

195 

27  Hz 

A 

221 

29  Hz 

A# 

250 

31  Hz 

B 

OCTAVE  TWO 

2 

24 

32  Hz 

C 

2 

56 

34  Hz 

C# 

2 

90 

37  Hz 

D 

2 

125 

39  Hz 

D# 

2 

163 

41  Hz 

E 

2 

203 

44  Hz 

F 

2 

246 

46  Hz 

F# 

3 

35 

49  Hz 

G 

3 

83 

52  Hz 

G# 
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TABLE  7-2.  POKE  Values,  Frequencies,  and  Musical  Equivalents  (continued) 


Upper  Tone 

Lower  Tone 

Frequency 

Musical 

POKE  Value 

POKE  Value 

Produced 

Note 

3 

-134 

55  Hz 

A 

/\ 

i 
3 

187 

58  Hz 

Aif 

1 

244 

62  Hz 

r> 
D 

OCTAVE  THREE 

4 

48 

65  Hz 

c 

4 

112 

69  Hz 

c# 

4 

180 

73  Hz 

D 

4 

251 

76  Hz 

D# 

5 

71 

82  Hz 

E 

5 

151 

87  Hz 

F 

D 

237 

92  Hz 

rtt 

0 

71 

98  Hz 

ri 

KJ 

/: 
0 

167 

104  Hz 

KJtt 

7 

/ 

12 

110  Hz 

A 

7 

119 

117  Hz 

Aif 

7 

233 

123  Hz 

r> 

D 

OCTAVE  FOUR 

8 

97 

131  Hz 

C 

8 

225 

139  Hz 

c# 

9 

104 

147  Hz 

D 

9 

247 

156  Hz 

D# 

10 

143 

165  Hz 

E 

11 

47 

175  Hz 

F 

1 1 
1 1 

218 

185  Hz 

rff 

142 

196  Hz 

ri 

VJ 

77 

208  Hz 

KJtt 

24 

220  Hz 

A 

r\ 

238 

233  Hz 

Ait 
/Ait 

i  s 

I  j 

210 

247  Hz 

r> 
D 

OCTAVE  FIVE 

16 

195 

262  Hz 

c 

17 

194 

277  Hz 

c# 

18 

208 

294  Hz 

D 

19 

238 

311  Hz 

D# 

21 

30 

330  Hz 

E 

22 

95 

349  Hz 

F 

23 

180 

370  Hz 

F# 

25 

29 

392  Hz 

G 

26 

155 

415  Hz 

G# 

28 

48 

440  Hz 

A 
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TABU  7-2.  POKE  Values,  Frequencies,  and  Musical  Equivalents  {continued) 


1  T  T>  

Upper  Tone 

Lower  Tone 

Frequency 

Musical 

f  vHV.IL  Value 

POKE  Value 

Produced 

Note 

29 

221 

466  Hz 

A# 

31 

164 

494  Hz 

B 

OCTAVE  SIX 

33 

134 

523  Hz 

C 

35 

132 

554  Hz 

C# 

37 

161 

587  Hz 

D 

39 

221 

622  Hz 

D# 

42 

60 

659  Hz 

E 

44 

191 

698  Hz 

F 

47 

104 

740  Hz 

F# 

50 

58 

784  Hz 

G 

53 

55 

831  Hz 

G# 

56 

97 

880  Hz 

A 

59 

187 

932  Hz 

A# 

63 

72 

988  Hz 

B 

OCTAVE  SEVEN 

67 

12 

1046  Hz 

C 

71 

8 

1 109  Hz 

C# 

75 

66 

1175  Hz 

D 

79 

187 

1244  Hz 

D# 

84 

121 

1319  Hz 

c 

89 

127 

1397  Hz 

F 

94 

209 

1480  Hz 

F# 

100 

117 

1568  Hz 

G 

106 

110 

1661  Hz 

G# 

112 

194 

1760  Hz 

A 

119 

118 

1865  Hz 

A# 

126 

145 

1976  Hz 

B 

OCTAVE  EIGHT 

134 

24 

2093  Hz 

C 

142 

17 

2217  Hz 

C# 

150 

132 

2349  Hz 

D 

159 

119 

2489  Hz 

D# 

168 

242 

2637  Hz 

E 

178 

254 

2794  Hz 

F 

189 

163 

2960  Hz 

F# 

200 

234 

3136  Hz 

G 

212 

220 

3322  Hz 

G# 

225 

132 

3520  Hz 

A 

238 

237 

3729  Hz 

A# 

253 

34 

3951  Hz 

B 
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make  unpredictable  sounds  or  no  sound  at  all.  To  set  up  the  SID  chip 
properly,  enter  these  statements: 

10  FOR  R=54272  TO  54296:   POKE  R,   0:  NEXT 

20  POKE  54296,  15 

30  POKE  54277,  0:    POKE  54278,    240:    POKE  54275,  8 

50  POKE  54276,  65 

As  you  read  this  chapter,  you  will  learn  the  uses  of  the  various  registers  and 
how  to  determine  your  own  POKE  values.  The  first  two  you  will  examine 
control  the  frequency  of  the  sound. 

POKEing  ATONE 

Table  7-2  shows  the  frequencies  the  SID  can  produce,  the  approximate 
musical  notes  achieved,  and  the  values  you  must  POKE  into  the  tone  registers 
to  generate  the  frequencies. 

The  lowest  audible  note  the  SID  can  produce  is  a  low  C  (approximately 
16  Hz,  or  16  cycles  per  second).  Enter  the  values  for  this  note  into  the  low  tone 
registers: 

POKE  54272,1 2= POKE  54273,1 

Then  turn  on  the  maximum  volume. 
POKE  54296,  15 

To  turn  off  the  sound,  you  can  use  any  of  the  following  methods: 

•  POKE  0  into  the  tone  registers. 

•  POKE  0  into  the  volume  register. 

•  Simultaneously  press  RUN/ STOP  and  RESTORE. 

The  first  method  puts  a  nonexistent  tone  value  into  the  tone  registers. 
The  second  method  turns  the  volume  register  to  the  minimum  position, 
which  is  OFF. 

The  third  method  resets  the  system  and,  therefore,  all  system  variables  — 
such  as  the  tone  registers,  screen  and  border  colors,  and  so  on.  It  is  better  to 
use  one  of  the  first  two  methods,  since  the  third  method  may  do  more  than 
you  had  in  mind. 
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THE  COMPONENTS  OF  SOUND 

Pure  Tones 

With  the  control  register  values  you  have  been  using,  the  SID  produces 
continuous  frequencies  ranging  from  about  1  Hz  to  3995.669  Hz.  In  tonal 
frequencies,  a  cycle  refers  to  a  sound  that  starts  at  its  minimum  volume,  rises 
to  its  maximum  volume,  and  falls  again  to  its  minimum  volume. 


Maximum  Volume 


Time 


Minimum  Volume 


The  actual  tone  of  a  sound  is  a  direct  function  of  its  frequency  (how 
quickly  it  rises  and  falls).  If  you  double  the  frequency,  you  will  have  a  tone 
exactly  one  octave  higher  than  before.  Try  this  program. 

10  REM:   CLEAR  SOUND  REGISTERS 

20  FOR  R=54272  TO  54296 J   POKE  R,0s  NEXT 

30  REM  SET  UP  REGISTER  #1 

40  POKE  54274,   0:   POKE  54275,  8 

50  POKE  54278,   240:   POKE  54296,    15 1  T«l 

60  POKE  54277,   O:   POKE  54276,  65 

70  REM:   READ  FUNCTION  KEYS 

90  GET  A*:    IF  A*~""  THEN  120 

100   IF  A*=CHR*(133)   THEN  160 

110  IF  A*«CHR*<134)   THEN  170 

120   IF  A»*CHR*(135)   THEN  180 

130  IF  A*=CHR*<136)   THEN  200 

140  GOTO  90 

150  REM:   POKE  TONES  INTO  SOUND  REG,  #1 
160  POKE  54272, 48: POKE  54273,   4: GOTO  90 
170  POKE  54272, 97: POKE  54273,  8 i GOTO  90 
180  POKE  54272, 195: POKE  54273, 16: GOTO  90 
190  REM:   TOGGLE  VOLUME  CONTROL 
200  IF  T=»l  THEN  POKE  54296 , 0 :  T*- 1 1  GOTO  90 
210  POKE  54296,    15 i   T»l:   GOTO  90 
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Line  20  POKEs  zero  into  all  the  tone  registers,  which  clears  them.  This 
prevents  them  from  generating  random  sounds  before  you  enter  the  sound 
you  want  into  them.  Every  time  you  want  to  POKE  a  tone  value  into  a  sound 
register,  you  must  use  two  values  because  the  C-128  has  a  range  of  65,535 
different  tones,  but  a  single  memory  location  can  only  hold  256  different 
numbers  (255  if  you  don't  count  0,  which  produces  no  sound).  So  to  produce 
the  full  range  of  65,535  different  sounds,  the  C-128  uses  two  memory  loca- 
tions for  each  tone  value.  The  numbers  in  those  two  locations  combine  to 
make  a  number  that  is  between  0  and  65,535. 

The  number  produced  by  these  two  memory  locations  is  represented  as  a 
16-bit  binary  number,  but  you  don't  have  to  understand  binary  numbers  to 
use  the  sound  registers;  just  use  Table  7-2  to  find  the  note  you  want  and  POKE 
the  indicated  values  into  the  sound  registers. 

Lines  40-60  set  up  the  sound  register  for  continuous  tones  just  as  you  did 
earlier.  Lines  90-130  read  the  function  keys  and  branch  to  the  routines  that 
play  the  note  C  in  one  of  three  different  octaves  (in  lines  160-180). 

If  you  press  F7,  you  will  branch  to  line  200,  which  turns  the  sound  ON  or 
OFF.  The  program  then  branches  back  to  line  90  and  waits  for  you  to  press 
another  key. 

SWEEPING  THE  SCALES 

You  can  change  the  value  in  a  tone  register  while  it  is  on,  which  imme- 
diately switches  one  note  to  another.  This  is  especially  useful  for  sliding  from 
one  note  to  the  next.  Try  the  following  example: 

10  FOR  R-54272  TO  54296a   POKE  R,Oi  NEXT 

20  POKE  54272,   O*   POKE  54273,  O 

30  POKE  54274,   Oi   POKE  54275,  8 

40  POKE  54278,   240 1   POKE  54296,  15 

50  POKE  54277,   Oi  POKE  54276,  65 

60  FOR  F»0  TO  65535  STEP  25& 

70  H»INT(F/256) i   L-INT <F- <256*H) ) 

80  POKE  54272,   Li  POKE  54273,  H 

90  NEXT 

100  FOR  R-54272  TO  54296 8  POKE  R,0*  NEXT 

This  program  sweeps  the  entire  range  of  tones  in  the  C-128  in  increments 
of  256.  You  can  make  the  steps  smaller  or  larger  by  changing  the  STEP 
number  in  line  50. 

Line  60  contains  the  routine  for  converting  decimal  numbers  between  0 
and  65535  into  the  correct  POKE  values  for  the  tone  registers.  You  can  use 
this  routine  to  create  any  tone  you  want. 
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MULTIPLE  TONES 

By  sounding  two  or  more  tones  at  once,  you  can  add  depth  to  many  of 
your  sound  effects.  Adding  these  lines  to  the  sample  program  will  play  two 
tones  at  once. 


25  POKE  54281,   0:   POKE  54282,  8 
35  POKE  54285,  240 
45  POKE  54284,   0:   POKE  54283,  65 
75  POKE  54279,   Ls   POKE  542S0,  H 

You  can  also  harmonize.  Type  NEW  and  enter  the  following  program: 

10  REM    CLEAR  SOUND  REGISTERS   

20  FOR  R=54272  TO  54296:   POKE  R,0:  NEXT 

30  REM    SET  -  UP  TONE  REGISTERS   

40  POKE  54274,   0:   POKE  54275,  8 

50  POKE  54281,   O:   POKE  54282,  8 

60  POKE  54288,   0:   POKE  54289,  8 

70  POKE  54278,   240s   POKE  54296,  15 

80  POKE  54285,   240  :  POKE  54292,  240 

90  POKE  54276,   65  s   POKE  54283,   65  s   POKE  54290,  65 

lOO  REM    TURN  ON  TONES   

110  POKE  54273,    16:   POKE  54272,  195 

120  FOR  G-0  TO  500:  NEXT 

130  POKE  54280,   21:  POKE  54279,  30 

140  FOR  G»0  TO  500:  NEXT 

150  POKE  54287,   25:   POKE  54286,  29 

160  FOR  G«0  TO  500*  NEXT 

170  FOR  G*0  TO  1500:  "NEXT 

180  REM  TURN  OFF  TONE  REGISTERS  

190  FOR  R=54272  TO  54296:   POKE  R,0:  NEXT 

With  careful  planning,  you  can  make  listeners  think  they  are  hearing 
more  than  three  sound  registers.  Try  adding  these  lines. 

162  POKE  54273,   33:   POKE  54272,  134 
165  FDR  G=0  TO  500   :  NEXT 


PULSED  TONES 

Another  way  to  modify  the  sound  registers  is  to  quickly  turn  them  ON 
and  OFF.  This  method,  called  pulsing,  can  create  the  effect  of  a  buzzer. 

To  get  a  better  idea  of  how  pulsing  works,  look  at  Figure  7-1  in  relation 
to  the  following  program: 

10  FOR  R»54272  TO  54296:   POKE  R,0:NEXT 
20  POKE  54274,   O:   POKE  54275,  8 
30  POKE  5427B,   240:   POKE  54296,  15 
40  POKE  54277,   O:   POKE  54276,  65 
50  FOR  T-0  TO   15  STEP  .3 
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60  POKE  "54272,   Oi   POKE  54273,  0 
70  FOR  F«0  TO  400:  NEXT 
80  POKE  54272,   67:   POKE  54273,  12 
90  NEXT 

1O0  POKE  54296,  0 

Lines  10  through  50  set  up  the  sound  registers,  but  there  is  no  sound 
output  until  the  tone  register  is  turned  on.  Line  60  starts  the  loop  that 
determines  the  number  of  pulses  produced  (this  program  uses  50).  Line  70 
starts  the  sound  at  0  (OFF),  as  shown  in  Figure  7-1 .  Line  80  is  the  delay  loop 
that  determines  the  OFF-time  for  the  pulse.  Line  90  turns  the  sound  ON.  Line 
100  completes  the  loop,  sending  the  program  back  to  line  60.  In  line  70,  the 
sound  is  immediately  turned  off  again.  After  repeating  50  times,  the  loop  ends 
at  line  110  by  turning  the  tone  register  off. 

By  increasing  the  length  of  the  delays  between  pulses,  you  can  tailor  this 
program  to  create  the  sound  of  a  bouncing  ping-pong  ball.  Change  line  80  as 
follows: 

70  FOR  F«0  TO  400:  NEXT 


POKE  36876, 
(pulse  on) 


200 


o 
> 


m  o 
O  o 


POKE  36876,  200 
(pulse  on) 


Be 
2a 


-POKE  36878,  15 


Time 


FIGURE  7-1.  Pulsed  waveforms 
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Volume  Adjustments 

Up  to  this  point,  you've  been  using  the  volume  control  as  an  ON/ OFF  switch. 
However,  it  can  also  be  used  to  change  the  nature  of  the  sounds  being 
produced.  You  can  produce  a  number  of  effects  simply  by  varying  the  volume 
of  a  tone. 


FADING  TONES 

By  slowly  reducing  the  volume  of  the  sound,  you  can  make  it  sound  like 
the  ball  is  bouncing  away.  First,  change  line  50  to  read  as  follows: 

50  FOR  T«0  TO  15  STEP. 3 

This  still  produces  50  steps  through  the  loop,  but  in  this  application,  T  must 
never  exceed  15  (the  highest  allowable  number  in  the  volume  register). 

Next,  POKE  the  loop  value  into  the  volume  register  by  adding  the 
following  line: 

55  POKE  54296,  15-T 

This  causes  the  volume  to  decrease  with  each  pass  through  the  loop. 

You  can  also  use  the  loop  variable  to  decrease  the  length  of  the  delays 
between  pulses  as  the  volume  decreases.  This  produces  a  sound  resembling  a 
dropping  ball.  Try  changing  line  70  to 

70  FOR  F~0  TO  400-T*26:  NEXT 

The  number  26  was  chosen  because  400  divided  by  15  is  approximately  26. 
This  divides  the  steps  of  the  delay  into  50  even  increments.  Subtracting  the 
loop  value  from  400  reduces  the  delay  in  the  increments  each  time  through  the 
loop. 

Try  changing  the  tones  used  in  the  first  ping-pong  program  to  produce 
the  sound  of  a  clock  ticking.  This  can  be  accomplished  by  using  two  different 
tone  values  on  alternate  loops. 

ATTACK/SUSTAIN/DECAY 

When  you  play  a  note  on  a  piano,  the  sound  begins  loudly  and  slowly 
fades  away.  The  start  of  the  sound  is  called  the  attack.  The  portion  of  the 
sound  in  which  the  volume  is  maintained  is  called  sustain,  and  the  last  part  of 
the  sound,  in  which  it  fades,  is  called  decay. 
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Sustain 


> 


Time 


All  of  the  sounds  produced  so  far  have  had  a  very  fast  attack  and  a  very 
fast  decay.  When  these  parameters  are  changed,  the  sounds  become  quite 
different.  Here  is  the  original  bouncing-ball  program  again. 

10  FOR  R=54272  TO  54296s   POKE  R,OiNEXT 

20  POKE  54274,   O:   POKE  54275,  8 

30  POKE  54278,   240 :   POKE  54296,  15 

40  POKE  54277,   0:   POKE  54276,  65 

50  FOR  T=*0  TO  15  STEP  .3 

60  POKE  54272,   0:   POKE  54273,  0 

70  FOR  F»0  TO  400:  NEXT 

80  POKE  54272,   67:   POKE  54273,  12 

90  NEXT 

100  POKE  54296,  0 

One  way  to  produce  a  decay  in  a  sound  is  by  adding  a  loop  that  causes  the 
volume  to  sweep  down  each  time  the  tone  is  produced. 

85  FOR  V»Q  TO  15:   POKE  54296, 15-V:NEXT 

If  you  also  add  some  lines  to  provide  attack,  the  program  looks  like  this. 

5   INPUT  "ATTACK" ;  A 
7   INPUT  "DECAY " ;  D 

10  FOR  R«54272  TO  54296:   POKE  R,0:NEXT 

20  POKE  54274,   0:   POKE  54275,  8 

30  POKE  54278,   240 i   POKE  54296,  15 

40  POKE  54277,   Oi   POKE  54276,  65 

50  FOR  T*0  TO  15  STEP  .3 

60  POKE  54272,   0:   POKE  54273,  0 

70  FOR  F»0  TO  400:  NEXT 

80  POKE  54272,   67:   POKE  54273,  12 

85  FOR  V»0  TO  15  STEP  A:   POKE  54296,  V:NEXT 

87  FOR  V-0  TO  15  STEP  D:   POKE  54296,  15~ViNEXT 

90  NEXT 

100  POKE  54296,  0 
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Listen  to  the  differences  introduced  by  different  attack /  decay  ratios.  You  can 
enter  any  positive  number,  including  fractions,  in  the  INPUT  statement.  If 
you  enter  0  for  either  the  attack  or  decay,  however,  the  note  will  never  end. 

Sustain  can  be  added  by  including  a  delay  between  the  attack  and  the 
decay  as  follows: 

9   INPUT   "SUSTAIN" ;  S 
86  FOR  SS-1  TO  S:  NEXT 


DECAYS  USING 
THE  BUILT-IN 
FUNCTIONS 

The  only  real  disadvantage  in  producing  attacks  and  decays  this  way  is 
that  any  of  the  effects  you  produce  will  affect  all  of  the  tone  registers. 
Depending  on  the  sounds  you  want  to  produce,  this  may  cause  problems. 

The  C-128  has  another  way  to  change  the  attack,  decay,  and  sustain  of  a 
tone.  The  key  to  this  method  is  in  the  sound  registers  in  Table  7-1. 

Figure  7-2  shows  the  attack  and  decay  control  registers  for  sound 
register  #  1 .  They  are  located  in  memory  location  54277. 

By  POKEing  values  between  0  and  15  into  the  lower  four  bits  of  this 
memory  location  (the  decay  register),  you  can  create  decays  of  different 
lengths. 

5   INPUT   "DECAY" \  D 

10  FOR  R=54272  TO  54296:   POKE  R,0:NEXT 
20  POKE  54274,   Oi   POKE  54275,  8 
30  POKE  54278,   Os   POKE  54296,  15 
40  POKE  54277,  D 
50  FOR  T-l  TO  1 


Bit  Values 


128  64  32  16 


4    2  1 


Attack  Control     Decay  Control 


FIGURE  7-2.  Memory  location  54277:  attack/ decay  control 


264    C-128  USER  GUIDE 


60  POKE  54272 f  67:  POKE  54273,  L2:  POKE  54276,  65 
70  FOR  F-OTO  1000  : NEXT : P0KE54273 , 0 :  P0KE54272,0r 

POKE  54276,  64 
80  NEXT 

90  POKE  54296,  O 

Notice  what  happens  as  you  use  different  decay  values.  The  smaller 
values  (shorter  decays)  drop  to  a  very  low  sound  level  much  sooner  than  the 
length  of  the  note  (which  is  determined  by  the  loop  in  line  85).  On  the  other 
hand,  the  longer  delays  drop  so  slowly  that  they  are  still  fairly  loud  when  the 
note  stops.  You'll  need  to  be  aware  of  the  amount  of  decay  you  are  introducing 
whenever  you  use  this  function  and  make  the  note  last  as  long  as  your  decay 
requires. 

ATTACKS  USING 
THE  BUILT-IN 
FUNCTIONS 

Producing  attacks  with  the  built-in  attack  function  is  nearly  identical  to 
producing  decays.  The  only  real  difference  is  that  you  need  to  place  the  attack 
values  in  the  upper  portion  of  memory  location  54277.  The  simplest  way  to  do 
this  is  to  multiply  the  attack  value  by  16  and  POKE  that  value  into  memory 
location  54277.  Try  changing  lines  5  and  40  as  follows: 

5  INPUT  "ATTACK" ;  A 
40  POKE  54277,   A*  16 

SUSTAIN 

When  you  run  this  program,  you  will  find  another  interesting  feature  of 
the  built-in  sound  functions.  The  shorter  attack  functions  cause  the  sound's 
volume  to  rise  abruptly  and  then  fall  just  as  abruptly,  maintaining  a  very  low 
volume  level  until  the  end  of  the  note.  This  happens  because  the  sound 
register  turns  the  volume  down  at  the  end  of  the  attack  function.  To  make  it 
continue  after  the  attack,  you  will  need  to  include  a  sustain  value  as  well.  This 
will  keep  the  tone  at  its  peak  value  until  the  sound  times  out.  This  can  be 
accomplished  by  POKEing  a  large  value  into  the  upper  half  of  the  sustain/ 
release  register  (memory  location  54278  if  you  are  using  sound  register  #  1)  in 
line  30. 

30  POKE  54278,   240 r   POKE  54296,  15 

Another  thing  to  look  at  is  the  longer  attack  functions.  If  the  time-out 
value  in  your  delay  loop  is  too  short,  the  sound  may  turn  OFF  before  it  reaches 
maximum  volume.  To  compensate  for  this,  you  may  need  to  increase  the 
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length  of  the  time-out  delay  if  you  are  using  very  long  attack  values. 

Sustain  can  also  be  accomplished  by  using  standard  delay  loops.  Here  is 
a  routine  that  produces  attacks,  decays,  and  sustains  using  only  delay  loops. 

10  INPUT  "ATTACK";  A 
20  INPUT  "DECAY" ;  D 
30  INPUT  "SUSTAIN" ;  S 

40  FOR  R-54272  TO  54296s   POKE  Rf Os  NEXT 

50  POKE  54274,   Oi   POKE  54275,  S 

60  POKE  54278,   240 i   POKE  54296,  15 

70  POKE  54277,   Oi   POKE  54276,  65 

80  POKE  54272,   Oi   POKE  54273,  0 

100  POKE  54272,   67:   POKE  54273,  12 

110  FOR  V-0  TO  15  STEP  A:   POKE  54296 ,  VsNEXT 

120  FOR  L«0  TO  S 

125  NEXT 

130  FOR  V=0  TO  15  STEP  Ds   POKE  54296,    15- VsNEXT 
140  POKE  54296,  O 


VIBRATO/TREMOLO 

Vibrato  and  tremolo  are  used  during  the  sustain  portion  of  the  tone. 
Vibrato  is  a  passage  in  which  the  volume  is  raised  and  lowered  quickly  to 
produce  a  wavering  effect.  Enter  the  following  lines  to  produce  vibrato: 

121  FOR  V=0  TO  S 

122  FOR  W=0  TO  7:  POKE  54296,    15-Ws  NEXT 

123  FOR  W»B  TO  15s POKE  54296,   W:  NEXT 
125  NEXT 


Tremolo  is  a  fast  vibrato.  If  you  change  lines  122  and  123  to 

122  FOR  W=15  TO  8  STEP  -Js   POKE  54296,   W:  NEXT 

123  FOR  W»8  TO  15  STEP  Js   POKE  54296,   Ws  NEXT 

and  add  an  INPUT  line  to  enter  the  vibrato  rate 
1  INPUT  "VIB.  RRTE";  J 

you  will  be  able  to  vary  these  parameters  at  the  start  of  each  tone.  Entering 
larger  numbers  will  increase  the  speed  of  the  vibrato,  and  entering  smaller 
numbers  will  slow  it  down.  Do  not  enter  numbers  larger  than  15;  they  will 
have  no  effect.  Entering  a  0  will  result  in  an  endless  loop. 


Mixing  Tones 

Earlier  in  this  chapter,  you  put  three  harmonizing  tones  together  to  create  a 
chord.  It  is  also  possible  to  combine  tones  to  create  entirely  new  sounds. 
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BEAT  FREQUENCY 

A  beat  frequency  is  a  sound  that  is  produced  when  two  tones  that  are 
very  close  together  are  played  at  the  same  time.  Try  the  following  simple 
experiment. 

10  FOR  R=54272  TO  54296i   POKE  R,Os  NEXT 
20  POKE  54275,   8:   POKE  54296,  15 
25  POKE  54282,  8 

30  POKE  54278,   240 i   POKE  54276,  65 
35  POKE  54285,   240:   POKE  54283,  65 
40  INPUT       STARTING  FREQUENCY";  F 
50  FF«F/. 06097 

60  H=INT (FF/256) s  L*INT  < (FF/256-H) $256) 
70  POKE  54272,   Ls   POKE  54273,  H 
BO  FOR  G-F-100  TO  F+100 
85  FO«G/. 06097 

87  H0=INT(F0/256) : LO»INT < (F0/256-H0) $256) 

88  POKE  54279,  LO:  POKE  54280,  HO:  NEXT 
90  FOR  R*54272  TO  54296*  POKE  R,Os  NEXT 


This  will  allow  you  to  hear  the  effects  of  different  notes  (frequencies)  on  each 
other.  Listen  for  the  "beat"  that  occurs  at  certain  frequencies.  This  is  caused 
by  the  interaction  of  the  two  tones. 


Selecting  Waveforms 

Up  to  this  point,  you  have  been  making  sounds  using  only  one  waveform  — 
square  waves.  In  addition  to  these,  the  C-128  can  produce  three  other  kinds  of 
sounds.  These  sounds  are  produced  by  the  different  kinds  of  waveforms 
produced.  They  are  triangle,  sawtooth,  and  white  noise. 

If  you  look  at  the  shapes  of  the  waveforms,  it  is  easy  to  see  how  they  affect 
the  sound.  For  example,  square  waves  rise  sharply,  stay  at  that  high  level  for 
exactly  half  of  their  period,  and  then  fall  sharply,  staying  low  for  the  other 
half. 


Maximum 


6 


Vok 
1  Cyclt 
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Sound  \* 

/ave 

Time  ► 

Minimum  Volume 
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These  kinds  of  square  waves  are  called  symmetrical  square  waves 
because  they  are  at  their  high  level  for  exactly  as  long  as  they  are  at  their  low 
level.  You  can  modify  this  symmetry  by  changing  the  pulse-width  registers. 
For  sound  register  #  1 ,  these  are  memory  locations  54274  and  54275.  Here  is  a 
routine  that  sounds  a  single  tone  while  sweeping  the  pulse  width  from  one  end 
of  its  range  to  the  other  in  increments  of  16. 

10  FOR  R-54272  TO  54296i   POKE  R,0:  NEXT 

20  POKE  54272,    15s   POKE  54273,  10 

30  POKE  54296,    15:   POKE  54278,  240 

40  POKE  54276,  65 

50  FOR  R«0  TO  4095  STEP  16 

60  H-INT (R/256) a  L=R-256*H 

70  POKE  54274,   Li   POKE  54275,   H:  NEXT 

80  FOR  G-F-100  TO  F+100 

90  FOR  R-54272  TO  54296:   POKE  R,0:  NEXT 

When  this  program  runs,  the  sound  begins  as  a  buzzy,  tinny  sound.  As 
the  pulse  width  becomes  more  symmetrical,  the  sound  becomes  fuller.  At  the 
upper  end  of  the  pulse-width  sweep,  the  sound  becomes  buzzy  again. 


1  Cycle    t  1  Cycle   ,1  Cycle  ,   1  Cycle  ,   1  Cycle  ,    1  Cycle   ,1  Cycle 


1%  10%         30%        50%  70%         90%  99% 


Pulse  width  ratio  (per  100%)  sweep  up 


The  triangle,  sawtooth,  and  white  noise  registers  are  not  affected  by  the 
pulse  width.  To  turn  on  the  triangle  waveform,  change  line  40  to  POKE  the 
waveform  control  register  (54276)  with  17  instead  of  65. 

40  POKE  54276,  17 

For  a  sawtooth,  POKE  54276  with  33  instead  of  17. 
40  POKE  54276,  33 

To  turn  on  the  white  noise  register,  use  129  instead  of  33. 
40  POKE  54276,  129 
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USING  THE  NOISE 
REGISTER 

The  noise  register  operates  exactly  like  the  tone  registers.  Here's  a 
bouncing-ball  program,  this  time  using  the  noise  register. 

10  FOR  R-54272  TO  54296:   POKE  R,0:NEXT 
20  POKE  54274 ,  Oi  POKE  54275,  8 
30  POKE  54278,   240:   POKE  54277,  0 
40  POKE  54296,  15 

50  POKE  54272,   67 i   POKE  54273,  12 

60  FOR  T»0  TO  15 

70  POKE  54276,  128 

80  FOR  F=0  TO  400a  NEXT 

90  POKE  54276,  129 

100  NEXT 

110  FOR  R*=54272  TO  54296:   POKE  R,OiNEXT 


Now  add  some  decay  to  the  sound. 

30  POKE  54278,   0:   POKE  54277,  9 
95  FOR  N=OTQ500:  NEXT 

By  also  modifying  the  repeat  rate  as  follows,  you  can  create  a  sound 
similar  to  a  train: 

80  FOR  F*0  TO  400-26*T:  NEXT 

By  mixing  sound,  you  can  also  add  a  train  whistle.  Add  the  following 
lines  to  your  program: 

11  POKE  54285,   Or   POKE  54284,  13 

12  POKE  54280,   16i  POKE  54279,  195 
110  FOR  T»0  TO  150 

120  POKE  54276,  128 

125  IF  T=30  OR  T-35  OR  T=70  OR  T-75  THEN  180 

130  POKE  54276,  129 

140  POKE  54296,  15-T/10 

150  FOR  N*0T0500-T*3r  NEXT 

160  NEXT 

170  GOTO  200 

180  POKE  54283,   32a  POKE  54283,  33 
190  GOTO  130 

200  FOR  R«54272  TO  54296s   POKE  R,0:NEXT 


PROGRAMMING  MUSIC 
ON  THE  C-128 

By  POKEing  values  and  delays  into  the  sound  registers,  you  can  write  song 
programs. 


5  REM  SET  UP  REGISTERS  

10  FOR  R-54272  TO  54296:  POKE  R, 0: NEXT 

20  POKE  5427S,   240:   POKE  54277,  0 

30  POKE  54296,  15 

33  REM    START  PLAYING  MUSIC   

40  POKE  54272,    134:   POKE  54273,  33 

50  POKE  54276,  17 

60  FOR  R-0  TO  200:  NEXT 

70  POKE  54276,  16 

BO  FOR  R-O  TO  100:  NEXT 

90  POKE  54276,  17 
100  FOR  R-0  TO  200:  NEXT 
110  POKE  54276,  16 
120  FOR  R-0  TO  100:  NEXT 
130  POKE  54272,    161:   POKE  54273,  37 
140  POKE  54276,  17 
150  FOR  R-0  TO  200:  NEXT 
160  POKE  54276,  16 
170  FOR  R-0  TO  100:  NEXT 
180  POKE  54272,   60:   POKE  54273,  42 
190  POKE  54276,  17 
200  FOR  R-0  TO  200:  NEXT 
210  POKE  54276,  16 
220  FOR  R-0  TO  100:  NEXT 
230  POKE  54272,    134:   POKE  54273,  33 
240  POKE  54276,  17 
250  FOR  R-0  TO  200:  NEXT 
260  POKE  54276,  16 
270  FOR  R-0  TO  100:  NEXT 
280  POKE  54272,   60s   POKE  54273,  42 
290  POKE  54276,  17 
3O0  FOR  R-0  TO  200 1  NEXT 
310  POKE  54276,  16 
320  FOR  R-0  TO  100s  NEXT 
330  POKE  54272,    161:   POKE  54273,  37 
340  POKE  54276,  17 
350  FOR  R-0  TO  600 i  NEXT 
360  POKE  54276,  16 
370  FOR  R-0  TO  lOOi  NEXT 
380  POKE  54272,   134*  POKE  54273,  33 
390  POKE  54276,  17 
400  FOR  R-0  TO  200 i  NEXT 
410  POKE  54276,  16 
420  FOR  R-0  TO  lOOi  NEXT 
430  POKE  54276,  17 
440  FOR  R=0  TO  200:  NEXT 
450  POKE  54276,  16 
460  FOR  R-0  TO  100*  NEXT 
470  POKE  54272,    161:  POKE  54273,  37 
480  POKE  54276,  17 
490  FOR  R-0  TO  200:  NEXT 
5O0  POKE  54276,,  16 
510  FOR  R-0  TO  100:  NEXT 
520  POKE  54272,  60:   POKE  54273,  42 
530  POKE  54276,  17 
540  FOR  R-0  TO  200:  NEXT 
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550  POKE  54276,  16 

560  FOR  R-0  TO  100:  NEXT 

570  POKE  54272,    134:   POKE  54273,  33 

580  POKE  54276,  17 

590  FOR  R-0  TO  600 i  NEXT 

600  POKE  54276,  16 

610  FOR  R-0  TO  lOOi  NEXT 

620  POKE  54272,    164:   POKE  54273,  31 

630  POKE  54276,  17 

640  FOR  R»0  TO  600 :  NEXT 

650  POKE  54276,  16 

660  FOR  R=0  TO  100*  NEXT 

670  POKE  54272,    134:   POKE  54273,  33 

680  POKE  54276,  17 

690  FOR  R»0  TO  200s  NEXT 

700  POKE  54276,  16 

710  FOR  R«0  TO  100 5  NEXT 

720  POKE  54276,  17 

730  FOR  R»0  TO  200 i  NEXT 

740  POKE  54276,  1& 

750  FOR  R»0  TO  lOOi  NEXT 

760  POKE  54272,    161s   POKE  54273,  37 

770  POKE  54276,  17 

780  FOR  R-0  TO  200 »  NEXT 

790  POKE  54276,  16 

800  FOR  R-0  TO  lOOi  NEXT 

810  POKE  54272,   60s   POKE  54273,  42 

820  POKE  54276,  17 

830  FOR  R-0  TO  200s  NEXT 

840  POKE  54276,  16 

850  FOR  R»0  TO  100:  NEXT 

860  POKE  54272,    191s   POKE  54273,  44 

870  POKE  54276,  17 

880  FOR  R-0  TO  200:  NEXT 

890  POKE  54276,  16 

900  FOR  R-0  TO  lOOt  NEXT 

910  POKE  54272,   60:   POKE  54273,  42 

920  POKE  54276,  17 

930  FOR  R-0  TO  200:  NEXT 

940  POKE  54276,  16 

950  FOR  R-0  TO  100:  NEXT 

960  POKE  54272*   161 1  POKE.  54273 ,  37 

970  POKE  54276,  17 

980  FOR  R-0  TO  200 1  NEXT 

990  POKE  54276,  16 

1000  FOR  R-0  TO  100 1  NEXT 

1010  POKE  54272*    134t   POKE  54273,  33 

1020  POKE  54276*  17 

1030  FOR  R-0  TO  200:  NEXT 

1O40  POKE  54276,  1& 

1050  FOR  R-0  TO  100:  NEXT 

1060  POKE.  54272,   144i   POKE  54273,  31 

1070  POKE  5427* ,  17 

1080  FOR  R-0  TO  200 1  NEXT 

1090  POKE  54276,  16 
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1100  FOR  R«0  TO  lOOt  NEXT 

1120  POKE  54272,   29 i  POKE  54273,  25 

1130  POKE  54276,  17 

1140  FOR  R*0  TO  200 i  NEXT 

ll50  POKE  54276,  16 

1160  FOR  R*0  TO   lOOi  NEXT 

1170  POKE  54272,   48 1  POKE  54273,  2B 

1180  POKE  54276,  17 

1190  FOR  R-0  TO  200i  NEXT 

1200  POKE  54276,  16 

1210  FOR  R-0  TO  100s  NEXT 

1220  POKE  54272,. 164:   POKE  54273,  31 

1230  POKE  54276,  17 

1240  FOR  R*0  TO  200 x  NEXT 

1250  POKf  54276,  16 

1260  FOR  R«0  TO   100s  NEXT 

1270  POKE  54272,   134:   POKE  54273,  33 

1280  POKE  54276,  17 

1290  FOR  R«0  TO  600:  NEXT 

1300  POKE  54276,  16 

1310  FOR  R=0  TO   100:  NEXT 

1320  POKE  54276,  17 

1330  FOR  R*0  TO  600:  NEXT 

1340  POKE  54276,  16 

1350  FOR  R-54272  TO  54296i   POKE  R,0:NEXT 


This  isn't  a  very  long  song,  but  the  program  is  long.  If  you  attempted  to 
put  all  of  the  notes  of  a  song  into  a  program  this  way,  you  would  probably  run 
out  of  memory. 

Another  way  to  enter  music  into  a  song  program  is  by  using  DATA 
statements.  A  program  of  this  type  requires  three  short  sections:  a  routine 
that  reads  the  notes,  one  that  plays  them,  and  one  that  contains  the  notes  as 
data.  Try  this  version  of  the  song. 


10  FOR  R-54272  TO  54296:   POKE  R,0:  NEXT 
20  POKE  54278,   240:   POKE  54296,  15 

30  DATA  134,33,200,134,33,200,161,37,200,60,42,200,134,33, 

200,60,42,200, 161,37 
40  DATA  600,134,33,200,134,33,200,161,37,200,60,42,200, 

134,33,600, 164,31,600 
50  DATA  134,33,200,134,33,200,161,37,200,60,42,200,191,44, 

200,60,42,200, 161,37 
60  DATA  200,134,33,200,164,31,200,29,25,200,48,28,200, 

164,31,200, 134,33,600, 134 
70  DATA  33,600,999,999,999 
80  READ  A,B,C 
90  IF  A-999  THEN  160 
100  POKE  54272,   A:   POKE  54273,  B 
110  POKE  54276,  17 
120  FOR  R-0  TO  C:  NEXT 
130  POKE  54276,  16 
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140  FOR  R-0  T0100:  NEXT 
150  GOTO  80 

160  FOR  R-54272  TO  54296:   POKE  R,0:  NEXT 

By  changing  the  values  in  the  DATA  statement,  you  can  play  almost  any  song 
you  like.  Enter  999  to  signal  the  end  of  the  song,  as  shown. 


Programming  Rhythm 

Programming  rhythm  on  the  C-128  is  much  like  programming  the  train 
sound  you  made  earlier.  Start  with  a  simple  drum  sound. 


10  FOR  R-54272  TO  54296:   POKE  R,0:  NEXT 
20  POKE  54277,   6:   POKE  54296,  15 
30  POKE  54272,    15 :    POKE  54273,  2 
40  DATA  375,150,165,999 
50  READ  A 

60  IF  A«999  THEN  100 

70  POKE  54276,  129 

80  FOR  R»  0  TO  As  NEXT 

90  POKE  54276,    128:   GOTO  50 

100  RESTORE:   GOTO  50 


By  using  another  tone  in  the  same  register,  you  can  add  a  bass  drum: 

10  FOR  R=54272  TO  54296:   POKE  R,Oa  NEXT 

20  POKE  54277,   6:   POKE  54296,  15 

30  POKE  54272,   15:   POKE  54273,  2 

40  DATA  33,375,129,150,129,165,999,999 

50  READ  A, B 

60   IF  A*999  THEN  100 

70  POKE  54276,  A 

80  FOR  R-0  TO  B:  NEXT 

90  POKE  54276,   0:   GOTO  50 

100  RESTORE:   GOTO  50 

Changing  the  loop  variable  will  vary  the  speed  of  the  rhythm. 
80  FOR  R«0  TO  B/2:  NEXT 


By  adding  some  additional  READ  and  DATA  statements  to  the  rhythm 
program,  you  can  include  a  melody.  Here's  the  complete  listing. 

10  FOR  R-54272  TO  54296=  POKR  R,  0:   NEXT  R 
20  POKE  54277,  40:  POKE  54296,  15 
30  POKE  54272,   15=  POKE  54273,  3 
35  POKE  54285,  240:  PQKE  54283,  17 

40  DRTfl  16,185,17,375,         18,208,129,150,  18,208,129, 

150,         19,238, 17,375 
50  DATA   19,238,129,150,  19,238,129,150,  18,208,17, 

375,  18,208, 129, 150 

60  DATA  18,208,129,150,         16,195,17,375,  16,195,129, 

150r  16, 195, 129. 150 
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70  DATA   16,195/17,375,  18,208,129,150,  18,208,129, 

150,  19,238, 17,375 

80  DATA  25,29,129,150,  25,29,129,150,  18,208,17, 

375,  19,238,129, 150 

90  DATA   19,238,129,150,  16,195,17,375,  16,195,129, 

150,  16, 195, 129, 150 

100  DATA  999,999,999,999 
160  READ  H,L,R,N 
170  IF  H=999  THEN  230 
180  POKE  54279, Li   POKE  54280,  H 
190  POKE  54276,  R 
200  FOR  M=0  TO  N:  NEXT 
210  POKE  54276,  0 
220  GOTO  160 
230  RESTORES   GOTO  160 

The  most  important  thing  to  keep  in  mind  when  working  with  this  kind 
of  program  is  that  doing  more  things  within  your  loops  (such  as  adding  more 
READ  statements)  adds  time  to  the  loop.  Test  statements,  such  as  the  one  on 
line  170,  also  take  some  time.  Be  sure  to  account  for  every  line.  If  you  are 
unsure  of  your  timing,  run  the  program  and  listen  for  timing  problems.  By 
adding  to  or  subtracting  from  the  timing  loops,  you  can  usually  compensate 
for  timing  errors. 


The  C-128 
Electronic  Organ 

Here's  a  program  that  GETs  notes  from  the  keyboard  and  plays  them.  The 
note  values  from  Table  7-2  have  been  used  and  POKEd  into  the  upper  and 
lower  tone  registers  of  sound  register  #  l . 

10  FOR  R=54272  TO  54296:   POKE  R,0s  NEXT 

20  POKE  54278,  240 

30  GET  A*:    IF  A*»MM  THEN  30 

40   IF  A$«"Q"  THEN  U«8iL»97 

50  IF  A*="2"  THEN  U=8»L*225 

60   IF  A*«"W"  THEN  U«9:L«104 

70  IF  A*«"3"  THEN  U«9sL»247 

80   IF  A*»"EM  THEN  U=»10iL~143 

90  IF  A*-"R"  THEN  U*11»L»47 

100  IF  A*»,,5"  THEN  U»ll:L=218 

110  IF  A*«MT"  THEN  U«12*L«142 

120   IF  A*«,,6"  THEN  U*13iL»77 

130  IF  A*-,,YM  THEN  U«14iL«24 

140  IF  A**M7"  THEN  U«l4iL»238 

150  IF  A*«"LP  THEN  U-15«L«210 

160  IF  A*»MI"  THEN  U«16xL=l95 

170  POKE  34272, Li  POKE  54273, U 

180  POKE  54296, 15 i   POKE  54276,  17 

190  FOR  6-0  TO  500 i  NEXT 

200  POKE  54296,0 j   POKE  54276,  16 

210  GOTO  30 
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This  program  was  written  for  only  one  octave.  By  increasing  the  number 
of  keys  read,  you  can  add  more  octaves.  To  make  the  keys  play  longer,  you  can 
increase  the  length  of  the  delay  loop  at  line  190  by  making  the  fractional 
STEP  smaller. 

C  C#  D  D#  E    F   F#  G  G#  A  A#  B 


II  IN 


w 


Saving  Music 

An  alternative  to  writing  DATA  statements  by  hand  is  to  use  the  electronic 
organ  to  store  your  musical  values.  You  will  now  see  how  to  save  them. 

CREATING  MUSIC  ARRAYS 

Adding  the  following  lines  to  your  program  will  allow  you  to  store  the 
notes  you  play  into  an  array.  For  the  purposes  of  this  program,  use  an  array 
with  100  notes  in  it.  You  can  create  arrays  with  more  notes  in  them  if  you  like, 
but  remember  that  each  note  is  2  bytes,  and  you  won't  be  able  to  dimension  an 
array  that  is  larger  than  your  available  memory  space. 

5  DIM  U(IOO),  L(IOO) 

31  IF  A*»M  {F3j  »  THEN  U<X)=Us   L(X)=Ls    X=X+1:   GOTO  30 

32  IF  A*<>"  {Fl}  "  THEN  40 

33  FOR  Z=»0  TO  X 

34  POKE  54272,   L(Z)s   POKE  54273,  U<Z> 

35  POKE  54296,    15 i   POKE  54276,  17 

36  FOR  G»0  TO  500:  NEXT 

38  POKE  54296,0i   POKE  54276,    16:  NEXT 

39  GOTO  30 

The  typeset  letters  in  braces  (such  as  {F3})  are  keys  that  you  should  press.  Each 
time  you  press  one  of  the  keys  on  the  keyboard,  it  will  be  played.  Pressing  Fl 
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will  play  back  all  of  the  notes  stored  in  memory.  To  add  a  note  to  the  song, 
press  F3  after  pressing  the  note  you  want. 

STORING  MUSIC  ON  THE 
DATASSETTE  OR  DISK 

When  you  turn  off  the  C-128,  any  music  you  have  stored  into  an  array 
will  be  lost.  If  you  want  to  save  your  songs  and  play  them  back  later,  you  will 
need  to  store  them  on  either  the  disk  drive  or  the  Datassette. 

Adding  the  following  lines  to  your  program  will  allow  you  to  store  the 
music  data  in  your  array  into  a  data  file  on  either  the  Datassette  or  disk  drive: 

45   IF  A*="  {F5}  "THEN  300 
300  INPUT   "FILE  NAME";  F* 

310   INPUT   "STORE  ON  [REVERSE  ON}D  {REVERSE  OFF}  ISK  OR 

{REVERSE  ON}  C  (REVERSE  OFF}  ASSETTE"  ;  S* 
320  IF  S*="D"   THEN  350 
330   IF  S*="C"  THEN  360 
340  PRINT"  (CURSOR  UP}  "  $  :  GOTO  310 
350  0PEN1,8,4,F*+", W":    GOTO  370 
360  0PEN1, 1, 1,F* 
370  FOR  2«0  TO  X 

380  PRINT#1,   U(Z):   PRINT#1 , L < Z >  :  NEXT 
390  CLOSE   1:   GOTO  30 

1000  0PEN15,8, 15 j INPUT#15, A,B*,C,D:   PRINTB*i CL0SE15&  END 

Now,  when  you  press  the  F5  function  key,  the  program  will  ask  you  for  a  file 
name  and  whether  you  want  to  save  the  song  on  disk  or  Datassette.  It  will  then 
store  the  contents  of  the  song  array  in  the  file  you've  specified. 

READING  MUSIC  FROM  THE 
DATASSETTE  OR  DISK 

To  read  a  song  from  a  music  file,  you  will  need  to  read  the  information 
back  into  an  array  that  can  be  read  by  your  electronic  organ  program.  The 
following  routine  accomplishes  this. 

55  IF  A**"  {F7}  "THEN  400 
400  INPUT  "FILE  NAME";  F* 

410  INPUT   "LOAD  FROM  {REVERSE  ON}  D  {REVERSE  OFF}  ISK  OR 

{REVERSE  ON} C {REVERSE  OFF}  ASSETTE"  j  S* 
420  IF  S*="D"  THEN  450 
430  IF  S**="C"  THEN  460 
440  PRINT"  {CURSOR  UP} "  $  s  GOTO  410 
450  0PENl,8,4,F*+",R"x   GOTO  470 
460  0PEN1, 1, 0,F*  3  J»0 

470  INPUT#1,   U(J):    INPUT#1 , L ( J) : BB=STi J=J+1 
480  IF  BB»0  THEN  470 
490  X«J: CLOSE  1:   GOTO  30 

1000  0PEN15,  8,  15s  INPUT#15,  A,B*,C,Di   PRINTB*!  CLQSEiSi  END 
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Once  you  have  added  these  lines  to  the  program,  you  can  use  the  F7  function 
key  to  load  songs  that  you  have  stored.  When  you  press  the  F7  function  key, 
the  program  will  ask  you  for  a  file  name  and  whether  you  want  to  load  from 
disk  or  Datassette.  It  will  then  load  the  song  array  from  the  file  you've 
specified. 


COMBINING  SOUND 
WITH  ANIMATION 

Most  video  games  use  sound  very  effectively.  The  sounds  can  be  used  to  create 
a  mood  or  to  give  the  player  more  information  about  the  action  taking  place 
on  the  screen. 


Timing 

When  playing  a  video  game,  the  player  is  more  dependent  on  the  timing  of  the 
sound  than  on  the  visual  portion  of  the  game.  Try  this  bouncing-ball  program 
with  no  sound. 

5  PRINT"  {CLEAR  HOME}  M 
10  A*=" 

20  FOR  R«0  TO  2:   PRINT  A*;:  NEXT 

30  FOR  T-1104  TO  1143 

40  FOR  Y«0  TO  10:  NEXT 

50  POKE  T-1,32:  POKE  T,81:  NEXT 

60  FOR  T-1143  TO  1104  STEP  -1 

70  FOR  Y-0  TO  10 i  NEXT 

80  POKE  T+1,32:   POKE  T,   81 I  NEXT 

90  GOTO  30 

Now  add  sound  with  the  following  lines: 

15  FOR  1=54272  TO  542968   POKE   1,0:  NEXT 

16  POKE  54272,  12i   POKE  54273,36 

17  POKE  54296,  15 i   POKE  54278,  240 
55  POKE  54276,  17 i   POKE  54276,  O 
85  POKE  54276,  17:   POKE  54276,  0 

The  addition  of  sound  helps  create  the  effect  of  a  bouncing  ball. 

To  synchronize  the  sound  with  an  action,  you  will  have  to  be  aware  of  the 
position  of  the  objects  on  the  screen.  In  the  example  just  given,  the  timing  was 
straightforward  because  the  sound  was  created  at  the  end  of  each  loop.  To 
make  simple  sounds  synchronize  with  movements,  the  sounds  should  gener- 
ally take  place  when  one  object  collides  with  another.  The  following  program 
determines  object  movement  and  sound  based  on  the  numeric  position  on  the 
screen: 
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10  FOR  J>54272  TO  54296 1   POKE  1 ,0s  NEXT 

20  POKE  54272,    12i   POKE  54273,36 

25  POKE  54279,    12:   POKE  54280,100 

30  POKE  54296,    15i    POKE  54278,  240 

35  POKE  54285,  240 

40  A*=" 

50  PRINT"  {CLEAR  HOME}";  i FOR  R»0  TO  5:   PRINTA*t  8  NEXT 

60  Bl-1104*   B2-11448  Rl-H  R2-.7 

70  POKE  B1,81j   POKE  Bl-1,32:   POKE  Bl+1,32 

80  POKE  B2,81t  POKE  B2- 1,32s  POKE  B2+l,32 

90  B1-B1+R1:  B2-B2+R2 

100  IF  Bl-1104  OR  Bl»1143  THEN  R1=R1 *-l t POKE  54276,17s 
POKE  54276,0 

110   IF  B2<1144.5  OR  B2>1182.5  THEN  R2-R2*- 1 s POKE  54283, 

17s   POKE  54283,0 
120  GOTO  70 

Because  different  tone  values  are  used,  it  is  immediately  apparent  which 
object  has  just  hit  the  wall. 


C-128  SPECIAL  SOUND 
AND  MUSIC  FEATURES 

In  addition  to  manipulating  the  sound  registers  in  the  SID  by  PEEKs  and 
POKEs,  you  can  create  sounds  and  music  with  a  number  of  special  sound 
commands  that  are  accessible  only  in  C-128  mode. 


SOUND 

The  most  basic  of  the  sound  commands  is  the  command  SOUND.  Its  simplest 
form  is 

SOUND  vffj 

where  v  is  the  voice  number  (1-3), /is  the  frequency  (0-65535),  and  /  is  the 
length  of  time  you  want  the  note  to  play  in  sixtieths  of  a  second.  For  example, 

lO  SOUND  1,286,60 

will  play  the  same  note  you  played  at  the  beginning  of  this  chapter  for  one 
second. 


SWEEPING  THE  SCALES 

The  d,  m,  and  s  parameters  of  the  SOUND  command  allow  you  to  sweep 
the  scales  in  an  assortment  of  ways.  With  these  parameters  the  SOUND 
command  would  look  like  this: 


SOUND  vj,kd,m,s 
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Of  course,  v,/,  and  /  are  the  same  as  before.  The  d  indicates  the  direction  of  the 
sweep  (0  sweeps  up  the  scales,  1  sweeps  down  the  scales,  and  2  oscillates  the 
frequency).  The  m  is  the  minimum  frequency  that  will  be  played,  and  the  s  is 
the  speed  at  which  the  scales  will  be  swept.  In  the  following  example,  the 
scales  are  swept  up,  swept  down,  and  then  oscillated. 

10  SOUND  1,11500,60,0,600,100 

20  FOR  R=0  TO  100:  NEXT 

30  SOUND   1 , 1 1500, 60, 1 , 600, lOO 

40  FOR  R=0  TO  100:  NEXT 

50  SOUND  1,11500,60,2,600,3000 

CHANGING  THE  SOUND 

The  last  two  parameters  available  with  SOUND  are  w  and  p.  The  vv 
controls  the  waveform  being  played.  Your  choices  are  0  (triangle  wave),  1 
(sawtooth),  2  (square  wave),  and  3  (white  noise).  Here  is  an  example  of  these 
four  sound  types: 

10  SOUND   1,  2048,60,0,0,0,0,0 

20  SOUND   1,  4096,60,0,0,0,1,0 

30  SOUND   1,  8192,60,0,0,0,2,1500 

40  SOUND  1,  2048,60,0,0,0,3,0 

PLAY 

The  PLAY  command  plays  music  based  on  their  actual  note  values 
(A,B,. .  .G).  Unlike  the  SOUND  command,  you  do  not  need  to  enter  any 
parameters  other  than  the  note  name  if  you  wish.  For  example,  the  line 

10  PLAY   "C  D  E  F  G  A  B" 

will  play  a  musical  scale. 

As  you  know,  the  C-128  can  produce  sounds  in  several  musical  octaves. 
To  select  one  of  the  octaves,  enter  the  parameter  0.  For  example,  the  following 
line  will  play  two  octaves: 

10  PLAY  "04  C  D  E  F  G  A  B  05  C" 

The  additional  parameters  available  with  PLAY  are  r  (musical  rest),  m 
(pause  until  the  end  of  a  measure),  w  (whole  note),  h  (half  note),  q  (quarter 
note),  i  (eighth  note),  and  s  (sixteenth  note).  If  you  incorporate  some  of  these 
parameters  into  a  musical  program,  you  can  play  a  song  very  easily  on  the 
C-128,  using  a  program  like  this: 

10  PLAY   "04  HCCD03  . H  B  04  Q  C  D" 
20  PLAY   "04  R  H  E  E  F  -H  E  04  Q  D  C" 
30  PLAY   "04  R  H  D  04  C  03  B  04  C" 
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ENVELOPE 

The  ENVELOPE  command  controls  the  attack,  decay,  sustain,  and 
release  of  a  sound  during  a  PLAY  command.  The  parameters  of  an  ENVE- 
LOPE command  are 

ENVELOPE  n,a,d,s,r,w,p 

These  parameters  are 

n:  envelope  number  (0-9) 

a:  attack  rate  (0-15) 

d:  decay  rate  (0-15) 

s:  sustain  level  (0-15) 

r:  release  rate  (0-15) 

w:  waveform  (same  as  SOUND  command) 

p:  pulse  width  (same  as  SOUND  command) 

By  manipulating  these  parameters,  you  can  produce  almost  any  kind  of 
sound.  Here  are  some  examples: 

10  ENVELOPE  0,12,0,12,0,4,540  :   GOSUB  40 
20  ENVELOPE  0,0,12,0,0,1,0:   GOSUB  40 
30  END 

40  PLAY   "TO  04  HCCD03  .HB04QCD" 
50  PLAY  "04  RHEEF  .HE  04  Q  D  C" 
60  PLAY   "04  R  H  D  04  C  03  B  04  C" 
70  RETURN 

The  TO  parameter  at  the  beginning  of  the  first  PLAY  line  tells  the  C-128  to 
take  the  envelope  information  from  envelope  0. 


TEMPO 

The  TEMPO  command  controls  the  speed  at  which  the  PLAY  command 
plays  its  notes.  It  ranges  from  0  to  255.  The  default  value  for  TEMPO  is  8, 
with  0  being  the  slowest  the  C-128  will  play  and  255  being  the  fastest.  Here  is 
an  example: 

lO  TEMPO  20 

20  ENVELOPE  0, 0, 12, 0, O, 1 f Oi   GOSUB  50 
25  FOR  R=0  TO  lOOO:  NEXT 
30  TEMPO  40:   GOSUB  50 
40  END 

50  PLAY  "TO  04  H  C  C  D  03  .H  B  04  Q  C  D" 
60  PLAY  "04  RHEEF  .H  E  04  Q  D  C" 
70  PLAY   "04  R  H  D  04  C  03  B  04  C" 
80  RETURN 


 CHAPTER 

Peripheral  Devices 


The  C-128  can  be  connected  to  many  peripheral  devices,  including  the  MPS 
803  printer,  the  Datassette,  and  the  1541  and  1571  disk  drives.  These  devices 
expand  the  capabilities  of  the  C-128  by  enabling  it  to  produce  permanent 
copies  of  its  output  on  either  paper  or  magnetic  media,  such  as  cassette  tapes 
or  floppy  diskettes.  Storing  information  on  magnetic  media  can  also  increase 
the  amount  of  memory  space  available. 

With  the  addition  of  a  modem,  the  C-128  can  communicate  by  telephone 
with  any  other  computer  that  has  a  similar  device.  The  modem  also  allows 
access  to  computer  networks,  which  provide  services  such  as  stock  market 
updates,  computer  shopping,  and  electronic  mail. 


STORING  DATA 


The  most  common  media  for  storing  data  on  microcomputers  are  floppy 
diskettes  and  magnetic  tape.  Diskettes  have  the  advantage  of  being  random 
access  devices  (that  is,  they  can  directly  store  or  retrieve  data  at  any  location 
on  their  surface).  Tapes  store  data  sequentially  (one  file  after  another)  and 
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must  be  manually  rewound  to  access  data  that  has  already  been  passed.  What 
they  lack  in  speed  and  flexibility,  however,  tape  systems  make  up  in  cost.  They 
are  much  less  expensive  than  disk  systems. 

FILES 

Computer  data  is  stored  in  files.  This  allows  you  to  locate  information  you 
have  placed  in  a  certain  category.  To  look  up  a  word  beginning  with  "C"  in  a 
dictionary,  you  would  turn  to  the  section  with  the  heading  "C."  Similarly,  to 
find  information  on  a  cassette  or  diskette,  you  would  instruct  the  computer  to 
locate  a  section  (file)  with  a  heading  (file  name)  you  assigned. 

C-128  data  files  can  have  names  that  are  much  longer  than  the  single- 
letter  headings  in  the  dictionary  (file  names  can  be  as  many  as  16  characters 
long).  The  length  of  the  files  is  limited  only  by  the  space  available  on  the 
diskette  or  cassette  tape.  The  number  of  file  names  on  both  1541  diskettes  is 
limited  to  144. 

There  are  two  kinds  of  files:  program  files  and  data  files. 

Program  Files 

Whenever  you  have  a  program  in  the  computer's  memory  that  you  wish  to 
save  in  order  to  use  it  again,  you  may  SAVE  it  on  tape  or  diskette.  To  read  it 
back  into  the  computer,  you  LOAD  it  into  memory.  You  should  give  each 
program  a  unique  name  so  that  the  computer  can  differentiate  one  file  from 
another.  When  you  are  using  the  Datassette  to  store  programs,  you  don't  have 
to  use  file  names,  since  the  computer  can  simply  be  instructed  to  LOAD  the 
first  program  it  encounters.  This  is  not  true  of  the  disk  drive.  You  must  tell  the 
computer  which  file  you  want  when  you  load  or  save  on  a  disk. 

To  use  a  program  file,  you  load  and  run  it,  just  as  if  you  had  entered  the 
program  by  hand.  The  advantage  is  that  you  do  not  need  to  enter  the  program 
by  hand.  In  general,  the  size  of  a  program  you  store  on  disk  or  tape  will  be 
limited  to  the  amount  of  memory  available  in  your  computer,  because  a 
program  is  normally  saved  in  its  entirety.  You  cannot  easily  save  part  of  a 
program  and  then  save  the  rest  of  the  program  later. 

One  way  to  handle  programs  that  will  not  fit  into  your  computer's 
available  memory  space  is  to  break  them  into  shorter  programs,  and  simply 
load  each  section  of  the  program  separately  and  run  it.  In  this  fashion,  you 
can  execute  programs  that  are  much  larger  than  the  memory  space  in  your 
C-128. 

If  you  decide  to  do  this,  make  sure  that  the  first  program  section  that  you 
load  is  longer  than  any  of  the  sections  it  calls.  This  is  necessary  because  the 
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program  variables  will  be  stored  at  the  end  of  your  program's  first  section;  if  a 
longer  routine  is  loaded  into  memory,  either  your  variables  or  part  of  the  new 
program  segment  will  be  lost. 

To  load  the  next  program  segment  from  within  a  program,  just  end  your 
first  segment  with  the  LOAD  command  in  the  format 

LOAD  "second program  name"\% 

This  will  load  and  run  the  next  segment. 

Data  Files 

Data  files  do  not  contain  programs,  so  they  cannot  be  loaded  and  run.  They 
contain  data  that  must  be  loaded  into  memory  by  a  program  or  entered  by 
you  in  immediate  mode. 

RECORDS  AND  FIELDS 

The  information  in  a  data  file  can  be  broken  up  into  records  and  fields. 
This  is  determined  by  the  program  reading  the  data  from  the  file.  To  better 
understand  this  concept,  consider  a  data  file  that  contains  a  passenger's  flight 
information  for  a  trip  from  New  York  to  San  Francisco  and  back. 


XYZ  AIRLINES  June  7,  1982 

John  Doe 

1234  Home  Place 

Small  Town,  New  Jersey 

FLIGHT  #303 

LEAVES  JFK  Int'l  1:45  PM  EST 
ARRIVE  SFO  Int'l   4:28  PM  PST 


XYZ  AIRLINES  June  9,  1982 

John  Doe 

1234  Home  Place 

Small  Town,  New  Jersey 

FLIGHT  #215 

LEAVES  SFO  Int'l  9:15  AM  PST 
ARRIVE  JFK  Int'l   4:45  PM  EST 


The  file  contains  information  for  the  departure  and  arrival  of  the  flights  John 
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Doe  is  taking  to  and  from  San  Francisco.  For  simplicity,  assume  that  it  is  a 
single  file  that  contains  two  records:  the  trip  to  San  Francisco  and  the  trip 
back  to  New  York. 

Each  record  contains  several  fields.  The  fields  are  the  groups  of  charac- 
ters that  form  either  complete  words  or  numbers.  For  instance,  the  word 
"JUNE"  contains  four  characters  (or  bytes)  that  are  stored  on  the  tape  or 
diskette  as  the  individual  characters  J,  U,  N,  and  E.  Logically,  however,  the 
characters  should  be  taken  as  the  whole  word  JUNE.  Similarly,  the  numbers 
2,  1 ,  and  5  should  be  taken  as  the  number  215 .  To  distinguish  the  data  within  a 
record,  it  is  important  that  the  fields  be  separated. 

Data  Transfer 

The  first  time  you  access  a  tape  or  diskette  file,  you  may  be  misled  into 
thinking  that  the  system  is  not  operating  correctly.  It  would  seem  logical  that 
the  disk  drive  or  Datassette  would  operate  each  time  the  program  reads  to  or 
writes  from  it.  This  will  occasionally  be  the  case,  but  not  always.  The  reason  is 
the  C-128  has  a  small  section  of  memory  allocated  as  a  data  buffer.  Each  time 
information  is  read  from  the  disk  or  Datassette,  the  buffer  is  filled.  Until  the 
data  is  exhausted  or  the  buffer  is  filled,  the  drive  or  Datassette  will  not  be 
accessed  again.  Similarly,  when  you  write  to  the  disk  or  Datassette,  data  is 
first  stored  in  a  buffer.  When  the  buffer  is  full,  all  the  data  it  contains  will  be 
stored  at  once. 

Logical  Files  and  Physical  Units 

Input/ output  programming  describes  any  programming  that  controls  the 
transfer  of  data  between  the  computer  and  a  peripheral  device,  such  as  the 
Datassette,  disk  drive,  or  printer.  These  are  all  external  physical  units.  In 
order  to  transfer  data  to  or  from  one  of  these  physical  units,  it  is  necessary  to 
indicate  which  one  you  are  accessing,  because  each  unit  has  a  specific  kind 
of  interface  and  a  particular  way  in  which  it  must  receive  its  input  (the 
computer's  output).  In  addition,  if  more  than  one  device  is  connected  to  the 
computer,  you  will  need  to  indicate  to  which  device  you  are  "talking." 

The  computer  can  also  receive  data  from  the  Datassette  and  disk  drive, 
and  the  data  it  receives  must  be  put  somewhere.  Look  at  the  problem  in 
programming  terms.  If  you  want  to  input  data  from  the  keyboard,  you  would 
use  a  BASIC  statement  such  as 

10  INPUT  R 

This  line  stops  program  execution  and  waits  for  you  to  enter  some  data  from 
the  keyboard  and  press  RETURN.  The  data  is  assigned  to  the  variable  A. 
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Unless  the  C-128  is  told  otherwise,  all  input  statements  such  as  this  one  look 
for  data  coming  from  the  keyboard. 

If  you  want  to  output  some  data  to  the  video  screen,  you  might  use  the 
following  statement: 

20  PRINT  R 

The  value  of  variable  A  will  appear  on  the  screen. 

The  INPUT  statement  tells  the  computer  it  is  to  receive  some  data,  and 
the  PRINT  statement  instructs  the  computer  to  output  some  data.  Although 
data  is  usually  sent  from  the  keyboard  and  received  by  the  video  screen,  these 
are  not  the  only  devices  available. 

To  "talk"  or  "listen"  to  another  device,  you  will  first  need  to  open  a 
logical  channel  to  that  device.  This  is  accomplished  by  using  the  OPEN 
statement.  With  this  statement,  you  designate  what  channel  you  are  using  and 
what  device  number  you  are  addressing.  Every  physical  unit  (peripheral 
device)  has  a  unique  device  number.  The  channel  you  open  is  called  the  file 
and  the  number  you  assign  to  it  is  its  file  number.  The  format  for  an  OPEN 
statement  is 

10  OPEN  fn,  dn,  sa,  filename 

where  the  variables  are  defined  as  follows: 

fn  The  file  number  is  the  number  you  use  to  access  the  file. 

You  may  choose  any  number  between  0  and  255. 

dn  The  device  number  is  the  number  of  the  peripheral 

device  you  are  addressing. 

sa  The  secondary  address  sets  up  certain  parameters  for  the 

device  being  used. 

filename  The  file  name  is  used  to  specify  the  file  during  a  read 

operation.  If  you  specify  a  file  name  when  you  write  the 
file  and  when  you  read  it  on  the  Datassette,  all  files  will 
be  skipped  until  the  one  you  specified  is  found. 

Table  8-1  shows  the  device  numbers  and  secondary  addresses  that 
correspond  to  the  C-128's  logical  devices. 

Datassette  Files 

Now  that  you  have  had  a  chance  to  look  at  files  in  a  general  way,  you  can  apply 
them  to  reading  from  and  writing  to  the  Datassette.  The  Datassette  is  the 
default  external  storage  device.  That  means  that  if  you  don't  specify  which 
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TABLE  8-1.  Device  Numbers  and  Secondary  Addresses 


Device 

Device 
Number 

Secondary 
Address 

Operation  Performed 

ivv  y  Ly  w    i  \s 

o 

None 

Cassette 

1 

0 
1 

Open  for  read 
Open  for  write 

Drive  # 

2 

2 

Open  for  write,  but  add  End- 
of-Table  mark  (EOT)  on  close 

Video 
Display 

3 

None 

Line  Printer 

Models  1526 

or  MPS  RfH 
vji  lvi  r  o  oi/j 

4  or  5 

7 

Alternate  character  set 

Disk 

Drives 

(all  models) 

8* 

0 
1 

2-14 
15 

Load  a  program  file  to  the 

computer 
Save  a  program  file  from  the 

computer 
Unassigned 

Open  command/ status  channel 

Other 
devices 
connected 
to  IEEE  488 
Bus 

5,6,7 
and 
9  through 
31 

Device  numbers  and  second- 
ary addresses  are  selected 
and  assigned  by  the  manufac- 
turer of  the  device  connecting 
to  the  IEEE  488  Bus. 

12  to  255 
unavailable 
at  this 
time 

♦Normally  8,  but  may  be  set  to  9,  10,  or  11  (see  the  section  on  multiple  disk 
systems). 

device  you  are  writing  to,  the  information  will  go  to  the  Datassette. 

For  example,  to  save  a  program  called  FILENAME  on  the  Datassette, 
you  would  type 

SAVE  "FILENAME" 

and  press  RETURN.  If  you  have  pressed  the  PLAY  and  RECORD  keys  on  the 
Datassette,  the  Datassette  will  start  operating.  After  your  program  has  been 
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saved,  the  Datassette  will  stop,  the  cursor  will  start  flashing  again,  and  the 
computer  will  display  READY  on  the  screen. 

LORD  "FILENRME" 

If  the  PLAY  button  has  been  depressed,  the  Datassette  will  operate  and  the 
computer  will  display 

SEARCHING  FOR  FILENAME 

As  it  passes  the  various  programs  that  precede  the  one  being  looked  for,  it  will 
display  their  names. 

FOUND  OTHERFILE 
FOUND  WRONGFILE 
FOUND  NEXTFILE 

When  the  program  requested  is  found,  it  will  display 

FOUND  FILENRME 
LOADING 

WRITING  DATA  FILES 

Writing  program  files  into  a  Datassette  file  is  a  simple  task.  Putting  data 
into  a  Datassette  file  is  almost  easy,  but  it  does  require  a  basic  understanding 
of  how  the  information  is  put  onto  tape. 

The  most  common  method  of  storing  data  is  by  printing  the  data  one 
item  at  a  time  to  the  Datassette.  This  can  be  done  by  entering  the  following 
statements. 

First,  you  will  need  to  open  a  file. 

10  OPEN  1,1,2, "DATA  FILE" 

This  will  open  a  Datassette  file  with  the  number  1  and  the  name  DATA  FILE. 
When  the  file  is  closed,  it  will  write  an  end-of-file  marker  onto  the  tape,  which 
indicates  to  the  C-128  that  no  more  records  exist  in  the  file. 
Now  you  can  enter  the  data  from  the  keyboard. 

20  INPUT  A* 

If  you  were  entering  numeric  data,  you  could  use  a  numeric  variable  such  as 
the  letter  A. 

At  some  point,  you  will  want  to  end  the  data  entry.  For  example,  if  you 
enter  XXX,  the  computer  will  branch  out  of  the  routine. 

30  IF  Ai  *  "XXX"  THEN  60 
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If  the  input  was  not  XXX,  you'll  want  to  save  it  on  tape 

40  PRINT#1 j  AS 
and  go  back  for  more  input. 

50  GOTO  20 
If  you  have  finished  entering  data,  close  the  file. 

60  CLOSE  1 

To  run  this  program,  you  should  first  wind  a  fresh  tape  all  the  way 
forward  and  rewind  it  again  until  you  can  see  where  the  nonmagnetic  leader 
and  the  actual  magnetic  tape  meet.  Make  sure  that  this  is  in  the  center  of  the 
cassette  opening  (see  Figure  8-1). 

Here's  the  complete  program. 

10  OPEN  1,1,2,    -"DATA  FILE" 
20  INPUT  Pit 

30  IF  fit  «  "XXX"  THEN  60 
40  PRINT#1,  A* 
50  GOTO  20 
60  CLOSE  1 


FIGURE  8-1.  Tape  position 
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Now  close  the  lid  and  run  the  program.  The  program  will  pause  (and  the 
cursor  will  disappear)  for  a  few  moments  while  the  file  is  opened  and  the  name 
of  the  file  is  written  onto  the  tape.  The  cursor  will  return  and  a  question  mark 
will  appear.  Enter  some  characters  and  press  RETURN. 

After  entering  a  few  items,  enter  XXX.  The  cursor  should  disappear 
again;  this  time,  the  file  is  being  closed  and  the  data  and  end-of-file  marker  are 
being  written  onto  the  tape. 

READING  DATA  FILES 

To  read  the  data  back  from  the  tape,  you  will  need  to  open  a  Datassette 
file  for  reading.  Add  the  following  lines  to  the  end  of  your  Write  Data 
program: 

70  PRINT  " REWIND  TAPE" 
80  PRINT  "WHEN  THE  TAPE  IS" 
90  PRINT  " REWOUND >  PRESS  STOP" 
100  PRINT  "ON  THE  DflTflSSETTE" 
110  PRINT  "THEN  HIT  <RETURN>" 
120  INPUT  C 

130  OPEN  1,1,0,    "DfiTfl  FILE" 

Lines  70  through  110  tell  the  operator  to  rewind  the  tape  and  to  signal  the 
C-128  when  the  rewinding  is  completed  by  pressing  RETURN.  Line  120  makes 
the  computer  wait  until  the  tape  has  been  rewound,  and  line  130  opens  the 
data  file  for  reading. 

Now  you  can  begin  reading  data  from  the  Datassette. 

140  INPUT#1,  A* 

This  inputs  the  first  record  you  entered  and  assigns  it  to  the  string  variable  A$. 
The  statement 

150  PRINT  AS 

takes  the  data  that  you  just  put  into  A$  and  displays  it  on  the  screen. 

Status  Register 

There  is  a  special  variable  name  (similar  to  TI  and  TI$)  that  indicates  the 
status  of  the  external  devices  connected  to  the  C-128.  This  is  the  variable  ST 
Table  8-2  interprets  the  values  of  ST. 

To  determine  whether  you  have  reached  the  end  of  a  file,  you  can  check 
the  value  of  ST  from  inside  your  program.  If  the  value  of  ST  is  64,  you  have 
run  out  of  data.  Add  the  following  line: 

160  IF  ST  O  64  THEN  150 


to 
o 
o 

TABLE  8-2.  Status  Byte  Returned  by  External  Devices  Via  Variable  ST  n 


Device 
Operation 

Status 

00000001 
Read  as  1 

00000010 
Read  as  2 

00000100 
Read  as  4 

00001000 
Read  as  8 

00010000 
Read  as  16 

00100000 
Read  as  32 

01000000 
Read  as  64 

10000000 
Read  as  128 

Read  from 

cassette 

drive 

Operation 
OK 

Operation 
OK 

Short 
Block. 
Data  block 
read  had 
fewer  bytes 
than  ex- 
pected 

Long 
Block. 
Data  block 
read  had 
more  bytes 
than  ex- 
pected 

Unrecov- 
erable 
read 
error 

Checksum 
error.  One 
or  more 
data  bits 
read  in- 
correctly 

End  of  file 
encounter- 
ed 

End  of  tape 
encountered 

Verify 

cassette 

drive 

Any 

verify 

mismatch 

None 

Disk 

drives 

(all 

models) 

Receiving 
device  not 
available 

Transmitting 
device  not 
available 

None 

None 

None 

None 

End  of  file 

Disk  drive 
not  present 
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Your  program  will  branch  back  to  read  another  record  from  the  file. 

IF  ST  equals  64,  all  the  data  has  been  read  and  displayed.  Close  the  file. 

170  CLOSE  1 

Then  follow  the  instructions  on  the  screen.  The  computer  will  display  all  of 
the  items  you  entered  in  the  previous  section. 

Using  GET#  to  Read  Files 

It  is  also  possible  to  use  the  GET  command,  just  as  you  would  from  the 
keyboard.  The  GET#  instruction  reads  one  byte  at  a  time  from  the  Datassette. 
Change  line  140  to 

140  0ET#li  fit 

and,  in  immediate  mode,  type 
GOTO  70 

This  time,  all  the  data  is  printed  in  a  vertical  column.  Why? 

Look  at  line  140.  The  GET#  function  inputs  only  one  character  at  a  time. 
That  character  is  then  assigned  to  variable  A$  and  printed.  The  computer 
then  invokes  a  carriage  return,  and  the  next  character  is  input  with  the  next 
GET#. 

At  the  end  of  each  string,  the  computer  automatically  adds  a  carriage 
return,  which  acts  as  a  delimiter  separating  one  string  from  the  next.  This  is 
usually  desirable,  since  it  causes  the  computer  to  separate  the  variables.  In 
some  applications,  however,  you  may  want  to  eliminate  the  trailing  carriage 
returns.  For  example,  you  may  want  to  conserve  space  in  a  tightly  packed  file 
in  which  all  the  variables  or  strings  are  of  the  same  length.  In  such  a  case,  you 
could  leave  out  the  carriage  returns  and  separate  the  variables  yourself. 

Remember,  however,  if  you  create  a  file  that  has  no  delimiters  (carriage 
returns),  you  must  separate  the  data  yourself  in  your  program.  To  suppress  the 
carriage  returns,  you  could  change  line  40  to  read 

40  PRINT#1 j  At; 

NOTE:  Generally  the  best  programs  are  the  ones  that  are  the  simplest. 
Therefore,  before  you  use  this  method  be  sure  that  you  need  to.  Also  be  aware 
that  a  file  with  no  delimiters  cannot  be  read  by  an  INPUT#  statement  unless  it 
contains  less  than  80  characters  because  the  INPUT  buffer  holds  only  80 
characters. 
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Disk  Files 

The  disk  drive  can  store  data  and  programs  just  as  the  Datassette  does.  The 
major  differences  between  the  disk  drive  and  the  Datassette  are  speed  and 
accessibility. 

The  disk  drive  can  access  data  much  faster  than  the  Datassette,  and  can 
access  them  randomly.  The  drive  can  access  any  location  on  the  disk's  surface 
to  read  or  write  data,  while  the  Datassette  must  read  and  write  all  data 
sequentially. 

HOW  DATA  IS  STORED  ON  DISKETTE 

The  data  is  stored  on  the  diskette  in  concentric  rings  called  tracks.  The 
1541  Disk  Drive  has  a  total  of  35  tracks  and  the  1571  has  a  total  of  70  tracks. 
Each  track  may  be  addressed  directly  and,  therefore,  may  be  quickly 
accessed.  In  general,  the  disk  drive  will  not  record  data  onto  an  entire  track. 
This  would  make  the  files  needlessly  long.  To  avoid  this,  each  track  is  divided 
up  into  sectors,  each  of  which  contains  256  bytes. 

Look  at  Figure  8-2.  You  will  see  that  the  tracks  on  the  diskette  are  not  the 
same  length.  The  ones  nearest  the  outer  edge  of  the  diskette  are  longer  than 
the  ones  near  the  center.  To  make  the  most  of  the  space  available  on  the 
diskette,  the  1541  and  1571  disk  drives  put  more  sectors  into  each  outer  track. 
The  number  of  sectors  per  track  varies  from  17  on  the  inner  tracks  to  21  in  the 
outer  tracks.  This  means  that  one  single-sided  1541  diskette  can  hold  176,640 
bytes  and  a  double-sided  1571  diskette  can  hold  363,280  bytes. 

DISKETTE  SECTORING 

If  you  manually  rotate  the  diskette  inside  its  jacket,  you  will  find  one  or 
more  small  holes  in  the  diskette  that  come  into  alignment  with  the  small  hole 
in  the  jacket.  If  there  is  only  one  hole,  the  diskette  is  soft-sectored.  If  there  are 
several  holes,  the  diskette  is  hard-sectored.  The  holes  in  the  hard-sectored 
diskette  are  used  on  some  disk  systems  to  position  the  sectors  on  the  diskette. 
Since  the  1541  and  1571  disk  drives  provide  their  own  special  sectoring,  you 
should  only  use  soft-sectored  diskettes. 

DISKETTE  DIRECTORY 

Track  18  on  the  1541  and  1571  diskettes  is  used  for  the  directory.  The 
directory  contains  the  names,  starting  sector  addresses,  and  file  types  of  all 
files  on  the  diskette. 

To  list  a  diskette's  directory,  load  it  into  memory  by  entering 

LORD  8 
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Tracks  1-17(21  sectors/ track) 
Tracks  18-24  (19  sectors/ track) 
Tracks  25-30  (18  sectors/ track) 
Tracks  31-35  (17  sectors/ track) 


FIGURE  8-2.  1541  / 1581  Diskette  sectoring  pattern  (by  tracks) 

The  name  of  a  directory  file  is  $  (dollar  sign),  and  you  are  loading  it  from 
device  number  8  (the  disk  drive).  To  list  the  diskette  directory,  simply  type 

LIST 

and  the  directory  will  be  displayed  on  the  screen. 

In  C-128  mode,  you  can,  as  an  alternative,  enter  the  command  DIREC- 
TORY. The  disk  directory  will  be  displayed  but  not  loaded  into  memory. 

THE  BLOCK  AVAILABILITY  MAP  (BAM) 

The  BAM  resides  on  track  18  of  the  diskette.  It  contains  information 
pertaining  to  memory  space  allocation  on  the  diskette. 
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INITIALIZATION 

Each  time  the  disk  drive  is  accessed,  it  compares  the  identifier  number  on 
the  diskette  with  the  ID  number  stored  in  disk  memory.  If  the  ID  numbers 
match,  the  disk  drive  proceeds  with  the  instruction  it  was  given.  If  there  is  a 
mismatch,  the  disk  drive  automatically  initializes  the  diskette. 

When  the  diskette  is  initialized,  the  contents  of  the  BAM  are  copied  into 
disk  memory.  This  tells  the  disk  drive  which  sectors  are  available  to  be  written 
to.  If  the  ID  numbers  of  two  diskettes  are  the  same,  the  disk  drive  will  not 
initialize  automatically.  It  will  not  update  the  BAM  with  the  allocation 
information  and  may  write  over  sections  of  other  programs  or  data.  To  avoid 
this,  format  your  diskettes  with  different  ID  numbers  whenever  possible. 

To  manually  initialize  a  diskette,  use  the  following  command: 

OPEN  1,8,15 

PRINT#1,  "INITIALIZE" 

A  shorter  version  of  these  commands  is 
OPEN  1,8,15,  "I" 

FORMATTING  A  DISKETTE 

Before  you  can  use  a  new  diskette,  you  must  format  it.  Formatting  writes 
a  disk  name,  an  ID  number,  and  all  of  the  track  and  sector  information  onto 
the  diskette  so  that  data  may  be  written  onto  it  by  the  C-128. 

To  format  a  diskette  that  has  never  been  used  before,  use  the  following 
commands  in  either  C-64  or  C-128  mode: 

OPEN  1,8,15 

PRINT#1 , "NEW • DISKNflME, ID" 

If  you  are  in  C-128  mode,  you  can  use  the  alternative  command: 

HEADER   "DISKNAME"  ,    HQ,  00 

The  disk  name  can  be  any  16-character  string  you  choose.  The  ID  can  be  any 
number  you  choose.  The  Disk  Operating  System  (DOS)  uses  the  ID  number 
to  determine  which  diskette  is  in  your  drive.  Remember  to  use  a  different 
number  for  each  of  your  diskettes;  then  the  disk  drive  will  always  be  able  to 
determine  whether  it  should  initialize  or  not.  If  all  of  the  IDs  of  your  diskettes 
are  different,  the  initialization  will  be  automatic;  otherwise,  you  will  need  to 
do  it  manually  each  time  you  change  diskettes. 

A  good  way  to  ensure  that  all  of  your  diskettes  have  different  IDs  is  to 
format  an  entire  box  of  diskettes  at  once,  numbering  them  sequentially.  When 
you  need  to  use  them,  you  can  perform  a  short  version  of  the  FORMAT 
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instruction,  which  erases  all  data  on  the  diskette  and  renames  it,  leaving  the 
ID  number  the  same.  Then  no  two  diskettes  in  the  box  will  have  the  same  ID 
number.  To  do  this,  use  the  following  FORMAT  instruction. 

NOTE:  This  will  not  work  on  new  (previously  unformatted)  diskettes. 

OPEN  1,8,15 

PRINT#1,    "N : DISKNflME" 

Notice  that  the  letter  N  is  used  instead  of  the  word  NEW.  N  is  an  acceptable 
abbreviation  for  the  NEW  (disk)  command. 

Renaming  Files 

If  you  have  a  file  with  a  name  that  you  feel  is  inappropriate,  you  may  change 
its  name  using  the  RENAME  instruction.  To  rename  a  file,  use  the  following 
format: 

OPEN  1 j  8  j 15 

PRINT*!/  "RENAME:  NEW  FILENAME  =  OLD  FILENAME" 

You  may  use  the  abbreviation  R  in  place  of  the  word  RENAME.  Thus,  if 
you  wanted  to  change  a  file  named  DOG.l  to  CAT.  1,  you  would  enter 

OPEN  1,8, 15 

PRINTil,    "R:   CAT. 1  ■  DOG. 1 " 

Erasing  Files 

To  erase  a  file  from  your  diskette,  use  the  SCRATCH  command.  Its  format  is 
shown  here. 

OPEN  1,8, 15 

PRINT#1,   "SCRATCH:  FILENAME" 

The  abbreviation  S  may  be  used  in  place  of  the  instruction  SCRATCH. 
Therefore,  you  can  also  use 

PRINT#1,    "S:  FILENAME" 

to  erase  programs  or  data. 

The  VALIDATE  Command 

The  VALIDATE  command  may  be  used  to  "clean  up"  a  diskette.  There  may 
be  some  files  on  your  diskette  that  were  not  properly  closed,  or  various  files 
that  were  used  as  temporary  storage  and  are  not  even  part  of  another  file.  To 
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perform  this  housekeeping,  use  the  VALIDATE  command  to  delete  any 
unclosed  files  and  free  any  blocks  that  were  previously  allocated  but  not 
associated  with  any  specific  file. 

Copying  Files 

You  can  make  a  copy  of  any  file  on  your  diskettes  by  using  the  COPY 
command.  The  same  command  with  slightly  different  syntax  will  concatenate 
diskette  files  as  well. 

To  make  a  copy  of  a  program  on  the  same  diskette,  use  the  following 
command  sequence: 

OPEN  15,8,15 

PRINT#15,   "COPV:  NEW  FILENRME  =  OLD  FILENAME" 

You  may  use  the  abbreviation  C  in  place  of  the  word  COPY,  as  in  the 
following  example: 

OPEN  15,8,15 

PRINT#15,   "C.D00.2  *  DOG. 1 " 

Disk  File  Concatenation 

Two  or  more  files  may  be  joined  together,  or  concatenated,  to  form  a  single 
file.  To  create  a  new  file  named  NEWFILE,  for  instance,  out  of  the  data  files 
OLDFILE.O,  OLDFILE.l,  and  OLDFILE.2  on  diskette,  use  the  following 
command: 

PRINT#1,    "C:    NEW  FILE  =  OLD  FILE  O,    OLD  FILE    1,    OLD  FILE  2" 

NOTE:  The  maximum  length  of  a  disk  command  string  is  40  characters, 
so  keep  your  file  names  short. 

Multiple-Disk  Systems 

If  you  have  a  system  with  more  than  one  disk  drive,  you  may  copy  files  from 
one  diskette  to  another.  Before  you  do,  however,  you  will  first  need  to 
differentiate  between  disk  drives.  When  the  1541  and  1571  disk  drives  are  first 
powered  up,  they  all  have  a  device  number  of  8.  If  you  connect  more  than  one 
disk  drive  to  your  system,  each  drive  will  need  a  different  device  number.  The 
device  number  may  be  either  8, 9, 10,  or  11 .  To  change  the  device  number  of  a 
disk  drive,  follow  these  instructions: 

1.  Turn  off  all  drives  except  the  one  you  are  changing. 
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2.  Open  a  command  file,  such  as 
OPEN  15,8, 15 

3.  Enter  the  following  command  sequence. 

NOTE:  Don't  worry  if  you  don't  understand  this  sequence;  this  kind 
of  instruction  is  covered  in  more  detail  in  the  section  called  "Diskette 
Memory  Manipulation." 

PR  I  NT#  1 5  J"  M-U  "  CHR$  (119)  CHR*  <  0  )  CHR*  C  2  )  CHR*  ( 9+32  )  CHRf  <  9+64  ) 

This  instruction  will  change  the  disk  to  device  number  9.  To  change 
the  disk  drive  to  another  device  number,  add  that  number,  instead  of 
9,  to  32  and  64  at  the  end  of  the  command. 

4.  Turn  on  the  next  drive  and  repeat  the  command  sequence,  using  a 
different  device  number  for  each  drive  added. 

NOTE:  Do  not  turn  off  any  drive  that  has  been  changed.  This  will  erase 
the  new  device  number. 

Disk  Data  Files 

Just  as  there  is  a  difference  in  the  way  that  data  files  and  program  files  are 
handled  by  the  Datassette,  there  is  a  difference  in  the  way  that  data  files  and 
program  files  are  handled  by  the  disk  drive. 

There  are  three  different  kinds  of  information  that  can  be  stored  on  the 
disk  drive.  The  first,  program  files,  has  already  been  covered.  The  second  is 
sequential  data  files  and  the  third  is  random  access  files. 

SEQUENTIAL  FILES 

Like  sequential  data  files  on  the  Datassette,  sequential  data  files  on  the 
1541  or  1571  disk  drive  must  be  opened  before  they  can  be  accessed.  To  open  a 
sequential  data  file  to  the  disk,  use  the  command  format 


OPEN  Ifn,  dn,  sa,  "drn:file  name ,SEQ,W 


where: 


Ifn 


is  the  logical  file  number. 

is  the  device  number  for  the  disk  drive. 


dn 


sa 


is  the  secondary  address.  You  can  use  any  number 
between  2  and  1 4.  Both  0  and  1  are  reserved  by  the  C- 1 28 
for  LOAD  and  SAVE  operations  and  1 5  is  used  to  open 
the  command  channel. 
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file  name 
SEQ 
W 


drn 


is  the  drive  number.  This  may  be  omitted  if  you  have  a 
one-drive  system. 

is  the  name  of  the  file  you  are  accessing. 

indicates  that  this  will  be  a  sequential  data  file. 

indicates  the  write  mode.  You  may  also  read.  The 
READ  command  may  be  abbreviated  as  R. 


Here's  an  example  of  writing  to  a  file  named  AIRLINE. 
OPEN  2,8,4,  *'0:fiIRLINE,SEG,W" 

Whenever  you  open  a  file  on  the  disk  drive,  the  red  activity  light  on  the 
front  of  the  drive  will  light  until  the  file  is  closed.  If  you  are  in  write  mode  and 
try  to  open  a  sequential  file  that  already  exists,  the  red  activity  light  will  flash, 
indicating  an  error  condition. 

If  you  want  to  write  over  a  file  that  already  exists,  you  can  modify  the 
OPEN  command  as  follows: 

OPEN  1 ,8, 10, "00 : AIRLINE, SEQ, W" 

The  @  tells  the  disk  drive  that  you  want  to  overwrite  the  data  in  the 
specified  file. 

If  the  file  does  not  exist,  the  normal  OPEN  procedure  will  be  carried  out 
by  the  disk  drive. 

USING  STRING  VARIABLES 
AS  FILE  NAMES 

You  can  use  a  string  in  place  of  a  file  name  if  you  want  to  generate  file 
names  from  within  a  program. 

Here's  an  example  of  a  program  that  asks  you  for  the  name  of  the  file 
before  it  is  opened.  This  allows  you  to  use  the  same  program  to  open  different 
files.  You  might  do  this  in  a  word  processing  program  that  has  different  names 
for  each  text  file. 

10  INPUT  "FILE  NAME" *  FN* 

20  OPEN  2,8,4,   ,l0:"+FN$+  **,W" 

Line  10  requests  a  file  name.  In  line  20,  the  file  name  is  concatenated  to  the 
OPEN  file  string.  This  is  important  because  the  OPEN  command  must  be  a 
single  string.  Using  the  plus  (+)  operator  accomplishes  this. 


PERIPHERAL  DEVICES  299 

CLOSING  DISK  FILES 

As  a  program  writes  data  to  a  disk  file,  the  data  is  first  written  to  a  buffer. 
When  the  buffer  is  full,  the  data  is  written  onto  the  diskette.  If  you  are  finished 
writing  data  to  the  diskette  and  the  buffer  is  not  yet  filled,  the  data  will  not  be 
written  onto  the  diskette  unless  you  close  the  file.  Closing  a  file  writes  the  data 
in  the  buffer  onto  the  diskette  whether  or  not  the  buffer  is  full.  Therefore,  it  is 
very  important  that  you  close  all  files  when  you  are  done  writing  data  to  them. 

NOTE:  You  may  keep  only  ten  files  open  with  the  C- 128,  and  only  five  of 
them  to  the  disk  drive.  Therefore,  it  is  advisable  to  close  channels  after 
reading  them  as  well  as  after  writing  to  them,  even  though  leaving  a  channel 
that  you  have  read  will  not  cause  the  same  kind  of  catastrophic  failures  as 
failing  to  close  a  file  that  has  been  written  to. 

The  PRINT#  Command 

The  PRINT#  command  is  used  to  transfer  data  to  the  disk  drive  or  any  other 
peripheral  device.  The  C-128  automatically  sends  a  carriage  return  at  the  end 
of  each  file  record  to  terminate  it  properly.  In  some  cases,  such  as  printing  to 
the  printer,  you  may  want  to  send  a  carriage  return  and  a  line  feed  to 
terminate  the  records  in  a  file. 

Use  logical  file  numbers  1  through  127  to  send  a  carriage  return  only,  and 
logical  file  numbers  128  through  255  to  send  a  carriage  return-line  feed  after 
each  record. 

Reading  a  Data  File 

The  INPUT#  and  GET#  statements  work  in  basically  the  same  way  on  disk 
files  as  they  do  on  Datassette  files.  The  INPUT#  statement  can  read  strings  no 
longer  than  80  characters.  To  read  longer  strings,  it  will  be  necessary  to  use 
GET#  and  read  the  strings  one  byte  at  a  time. 

Random  Access  Files 

You  can  create  random  access  files  by  directly  addressing  diskette  data  blocks 
and  memory  buffers.  Each  data  block  occupies  a  single  sector  of  the  diskette. 
There  are  eight  buffers  available  on  the  C-128,  but  four  of  them  are  used  for 
the  Block  Availability  Map,  variable  space,  command  channel  I/O,  and  the 
disk  controller.  This  leaves  you  with  only  four  buffers  for  random  access  files. 
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Be  sure  not  to  open  more  than  four  buffers  at  a  time.  Opening  more  than  four 
will  result  in  a  system  error. 

Information  is  written  to  diskette  random  access  files  using  the  PRINT# 
command.  The  files  are  specified  through  parameters  in  the  OPEN  statement. 
The  format  for  opening  a  random  access  file  is 

OPEN  lfn9  dn,  sa,  "#  buf" 

is  the  logical  file  number.  For  performing  data  transfers, 
use  logical  file  numbers  between  2  and  14.  To  perform 
any  utility  command,  use  logical  file  15.  In  general,  it  is  a 
good  idea  to  open  the  command  channel  ( 1 5)  and  a  data 
channel  for  each  operation. 

is  the  device  number. 

is  the  secondary  address  (it  must  have  a  value  between  2 
and  14). 

is  the  buffer  number  allocated  to  the  specified  secondary 
address.  You  do  not  need  to  use  this  specification.  If  you 
leave  it  out,  DOS  will  automatically  select  a  buffer. 

DISK  UTILITY 
INSTRUCTIONS 

The  C-128's  disk  utility  instructions  are  described  in  this  section.  Table  8-3 
provides  a  summary  of  these  commands. 

BLOCK-READ 

The  BLOCK-READ  command  reads  any  sector  (block)  into  one  of  the 
memory  buffers.  To  read  a  block,  you  would  first  need  to  open  the  command 
channel  (15)  as  follows: 

10  OPEN  15,8,15 

Next  a  direct  access  channel  must  be  opened. 
20  OPEN  2J8,4,,,#" 

You  can  select  which  block  you  want  to  read  (by  track  and  sector). 

30  INPUT  ''TRACK'';  fl 
40  INPUT  "SECTOR" i  B 


where: 
Ifn 


dn 

sa 


buf 
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TABU  8-3.  Disk  Utility  Instruction  Set 


Command 

Abbreviation 

Format 

BLOCK-READ 

B-R 

PRINT#15,  "B-R:"ch;dr;t;s 

BLOCK-ALLOCATE 

B-A 

PRINT#15,  "B-A:"dr;t;s 

BI  OCK-WRTTF 

B-W 

BLOCK-EXECUTE 

B-E 

PRINT#15,  "B-E:"ch;dr;t;s 

BUFFER-POINTER 

B-P 

PRINT#15,  "B-P:"ch;byte 

BLOCK-FREE 

B-F 

PRINT#15,"B-F:"dr;t;s 

MEMORY-WRITE* 

M-W 

PRINT#15,  "M-W:"CHR$(adrl)CHR$ 
(adrh) 

v--  n  iv  ^>\ff  vyics  ^nivji^udidjv^nixj) 
(data)... 

MEMORY-READ* 

M-R 

PRINT#15,  "M-R"CHR$(adrl)CHR$ 
(adrh) 

MEMORY-EXECUTE* 

M-E 

PRINT#15,  "M-E"CHR$(adrl)CHR$ 
(adrh) 

Ul 

UA 

Alternative  lor  DLvJCJv-KiiAlJ 

U2 

UB 

Alternative  for  BLOCK-WRITE 

U3 

UC 

Disk  Processor  JMP  $0500 

U4 

UD 

Disk  Processor  JMP  $0503 

U5 

UE 

Disk  Processor  JMP  $0506 

U6 

UF 

Disk  Processor  JMP  $0509 

U7 

UG 

Disk  Processor  JMP  $050C 

U8 

UH 

Disk  Processor  JMP  $050F 

U9 

UI 

Disk  Processor  JMP  $FFFA 

U: 

UJ 

Disk  Processor  JMP  power-up  vector 

*You  must  use  the  abbreviation  for  these  instructions. 

The  following  statement  reads  a  block  of  data  into  the  buffer: 

50  PRINT#15.  MB-R:u4j0jflJB 

Here  are  the  components  of  this  instruction. 

PRINT#15       to  perform  any  of  the  commands  in  this  section,  you 
must  use  the  command  channel  (15). 
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B-R: 


is  the  abbreviation  for  "BLOCK-READ:"  The  colon 
within  the  quotation  marks  positions  the  data  that  fol- 
lows the  instruction. 


0 


4 


is  the  secondary  address  from  line  20  (given  previously). 

is  the  drive  number.  This  is  mandatory  when  you  are 
using  the  direct  access  instructions. 


A 


is  the  track  number  that  was  input  in  line  30.  Although 
you  may  use  variables  to  designate  track  and  sector  in 
these  instructions,  a  constant  can  be  used  as  well. 


B 


is  the  sector  number, 


All  of  the  data  —  secondary  address,  drive  number,  track  number,  and 
sector  number  —  in  this  instruction  must  be  separated  by  semicolons,  as 
shown  in  the  example. 

Now  that  the  data  in  your  selected  block  has  been  transferred  to  the 
buffer,  you  will  need  to  use  an  INPUTS  or  a  GET#  statement  to  extract  it  from 
the  buffer. 

The  INPUT#  statement  retrieves  all  bytes  up  to  and  including  the  first 
carriage  return  it  finds.  Since  you  may  not  know  the  exact  data  in  a  sector 
before  you  read  it,  you  may  overrun  the  length  of  the  INPUT#,  which  can 
hold  only  80  bytes. 

Because  of  this  limitation  of  the  INPUTS  statement,  it  is  preferable  to 
use  the  GET#  statement  when  you  are  unsure  of  the  data  you  will  read.  It  will 
read  the  data  one  byte  at  a  time. 

£0  GET#2,  R* 

There  are  256  bytes  of  data  in  each  block,  but  not  every  block  is  full.  To 
read  all  the  data  in  a  block  and  stop  at  the  end  of  the  file,  test  the  status 
variable  (ST)  to  see  if  it  is  zero. 

70  IF  ST*0  THEN  PRINT  RSJ  :G0T0  68 

NOTE:  Although  there  is  a  trailing  semicolon  in  the  PRINT  statement, 
the  display  will  jump  to  the  next  line  whenever  it  reaches  a  carriage  return  in 
the  data,  separating  the  data  just  as  it  was  entered. 

If  ST=0,  there  is  still  more  data,  and  you  can  go  back  and  get  another 
byte.  Otherwise,  close  all  channels  when  you  are  done  with  them. 


80  CL0SE2  J  CLOSE 15 

Here  is  the  whole  BLOCK-READ  program. 
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10  OPEN  15,8,15 

20  OPEN  2,8,4,  "#" 

30  INPUT  "TRACK";  A 

40  INPUT  "SECTOR";  B 

50  PRINT#15,  "B-R:"4;0;A;B 

60  GET#2,  fl$ 

70  IF  ST*0  THEN  PRINT  fl$; :  GOTO  60 
80  CLOSE  2'  CLOSE  15 

BLOCK-ALLOCATE 

The  BAM  keeps  a  record  of  all  blocks  that  have  been  allocated  (contain  data). 
In  the  higher-level  instructions  (such  as  SAVE)  the  DOS  (Disk  Operating 
System)  uses  this  information  to  determine  where  data  can  be  written  on  the 
diskette. 

When  you  are  using  the  direct  access  functions,  however,  the  DOS  does 
not  use  the  BAM  and  you  can  write  anything  into  any  block  on  the  diskette, 
whether  or  not  it  already  contains  data.  You  can  write  data  anywhere,  even 
over  the  directory  and  BAM,  but  you  should  avoid  this.  You  can  lose  normal 
access  to  everything  on  your  diskette  if  you  write  to  it  indiscriminately.  It  is 
therefore  advisable  to  perform  a  BLOCK-ALLOCATE  instruction  before 
attempting  to  write  a  block. 

The  BLOCK-ALLOCATE  instruction  checks  a  sector  to  determine  if  it 
already  contains  data.  If  it  is  available  (as  indicated  in  the  BAM),  it  marks  the 
sector  as  allocated.  If  it  is  already  allocated,  it  leaves  the  BAM  unchanged  and 
indicates  the  next  available  sector  in  the  error  channel. 

Here  is  a  routine  to  perform  a  BLOCK-ALLOCATE. 

10  OPEN  15,8,15 

20  INPUT  "TRACK";  fl 

30  INPUT  "SECTOR";  B 

40  PRINT#15,  "B-fl:"0;fl;B 

The  components  of  the  BLOCK-ALLOCATE  instruction  are  as  follows: 


PRINTS  15, 


activates  the  command  channel 


B-A: 


is  the  BLOCK-ALLOCATE  instruction 


0 


is  the  drive  number 


A 


is  the  track  number 


B 


is  the  sector  number. 


Here  is  the  rest  of  the  routine. 
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60  INPUT#15,E,EM*,T,S 
70  PRINT  E.EM* 
80  PRINT  TiS 
90  CLOSE  IS 
99  END 

Alter  every  disk  operation,  the  disk  status  can  be  read  through  the  error 
channel.  This  is  accessed  by  reading  the  values  of  four  variables  available  to 
the  command  channel  (15).  In  the  case  of  a  BLOCK-ALLOCATE  instruc- 
tion, the  error  channel  will  tell  you  if  the  track  and  sector  you  chose  are 
available.  If  they  are  not  available,  it  will  give  you  the  number  of  the  next 
available  track  and  sector. 

Line  60  checks  the  error  channel,  putting  the  information  contained  in  it 
into  variables  E  (error  code),  EM$  (error  message),  T  (track),  and  S  (sector). 
Lines  70  and  80  print  the  data,  and  lines  90  and  99  close  the  channel  and  end 
the  program. 

If  you  were  using  this  as  a  subroutine  within  a  program,  you  could  use 
the  data  obtained  from  the  error  channel  to  allocate  another  block  if  the  one 
you  wanted  was  already  occupied,  since  the  next  available  track  and  sector 
will  have  been  placed  into  the  error  channel.  If  the  sector  is  free,  the  message 
OK  will  be  displayed. 

BLOCK-WRITE 

Whenever  you  use  BLOCK-WRITE,  you  should  perform  a  BLOCK- 
ALLOCATE  first  to  determine  if  the  sector  you  want  to  write  to  is  available.  If 
it  isn't,  you  will  know  the  next  available  sector. 

The  following  BLOCK-WRITE  program  uses  BLOCK-ALLOCATE  to 
check  the  selected  sector: 

10  OPEN  15,8,15 

20  INPUT  "TRACK";  fl 

30  INPUT  "SECTOR";  B 

40  PRINT#15,   "B-fl  •*  "0;  R;  B 

50  INPUT#15iEiEM$iTi8 

Now  you  must  look  at  EMS  to  determine  whether  the  sector  you  selected 
is  available. 

60  IF  EM*  *  "OK"  THEN  100 

If  it  isn't,  then  use  the  values  obtained  through  the  error  channel  as  your 
new  track  and  sector. 

70  fl*T 
80  B«S 
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NOTE:  If  there  are  no  more  available  sectors  on  the  diskette,  the  error 
channel  will  return  track  0  and  sector  0.  These  do  not  designate  a  real  sector 
and  will  cause  an  error  if  you  try  to  write  to  that  location.  To  make  sure  you 
don't  have  this  problem,  recheck  the  error  channel.  If  there  are  zeros  in 
variables  T  and  S,  then  you  need  to  check  for  sectors  with  lower  numbers. 

90  IF  ft«0  AND  B*0  THEN  PRINT  "DISK  FULL"  •'  GOTO  160 

If  you  don't  get  this  error,  continue  with  your  BLOCK-WRITE. 

100  PRINT  " TRACK "  i  ft  i " M  j " SECTOR M j B 
105  OPEN  2j8j4,"#" 
110  INPUT  Rf 

If  you  input  an  X,  the  program  will  terminate  data  input. 

120  IF  fit«,,Xu  THEN  150 
If  not,  then  put  the  data  into  your  file  by  using 

130  PRINT#2,  ft* 
and  go  back  for  more. 

140  GOTO  110 

Use  the  following  statement  to  put  the  data  into  your  selected  sector: 
150  PRINT#15,    "B-W: " 4 ; 0  j  R  J  B 

NOTE:  The  format  of  the  BLOCK-WRITE  instruction  is  the  same  as 
that  of  the  BLOCK-READ  instruction. 

You  must  close  your  files  and  end  the  program. 

160  CLOSE  2>  CLOSE  15 
BUFFER-POINTER 

As  you  have  seen,  the  data  buffer  stores  information  that  is  read  in  from  the 
diskette.  The  buffer  pointer  keeps  track  of  which  byte  is  being  read,  and 
advances  by  one  each  time  a  byte  is  read. 

Suppose  you  wanted  to  read  the  data  in  a  specific  240-byte  file  as 
separate  records.  The  first  record  resides  in  bytes  1  through  120  and  the  other 
is  restored  in  bytes  121  through  240.  Reading  the  files  in  order  would  be  easy 
because  the  BUFFER-POINTER  would  already  be  at  the  point  where  the 
second  file  starts  after  reading  the  first  file.  But  what  if  you  only  wanted  to 
read  the  second  file?  One  way  to  read  the  second  file  would  be  to  perform  120 
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GET#  instructions,  using  a  short  loop,  until  you  got  to  byte  121 .  This  can  be 
accomplished  more  easily,  however.  The  BUFFER-POINTER  instruction 
will  allow  you  to  point  at  any  byte  in  the  buffer.  Its  format  is 

PRINTS  15,  "B  P:"  sa;byte 

where: 

PRINT#15,        activates  the  command  channel 
"B-P:"  is  the  BUFFER-POINTER  command 

sa  is  the  secondary  address 

byte  is  the  byte  you  want  to  access. 

For  example,  if  you  wanted  to  GET  the  120th  byte  of  a  block,  you  would 

use 

PRINT#15,  MB-P:"4J15 

BLOCK-FREE 

The  BLOCK-FREE  instruction  will  deallocate  any  block  on  the  diskette. 
This  instruction  tells  the  BAM  to  mark  the  block  specified  as  available,  thus 
allowing  data  to  be  written  to  the  block. 

To  perform  a  BLOCK-FREE,  use  the  following  format: 

OPEN  15,8,15 

PRINT#15,  "B-F:"  dr;trk;sec 

where: 

PRINT#15,        activates  the  command  channel 
"B-F:"  is  the  BLOCK-FREE  command 

dr  is  the  drive  number 

trk  is  the  track  number 

sec  is  the  sector  number. 

Here  is  a  routine  you  can  use  to  free  any  block  on  the  diskette. 

10  OPEN  15,8,15 

20  INPUT  "TRACK";  R 

30  INPUT  "SECTOR";  B 

40  PRINT#15,  "B-F:"0;fl;B 

50  CLOSE  IS 

99  END 
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DISKETTE  MEMORY  MANIPULATION 

The  1541  and  1571  controllers  interpret  external  commands  and  cause  the 
disk  drive  mechanism  to  carry  them  out.  Each  controller  contains  a  6502 
microprocessor,  which  is  similar  to  the  one  inside  the  C-128.  It  has  2K  of 
RAM  and  the  Disk  Operation  System  (DOS),  which  is  contained  on  ROM 
chips. 

Some  parts  of  this  memory  are  used  for  the  buffers  discussed  in  the  last 
few  sections;  some  are  used  for  housekeeping  purposes,  such  as  maintaining 
the  BAM  data  and  special  file  information;  and  some  are  available  for  you  to 
use  for  special  applications. 

The  RAM  that  is  available  for  you  to  write  routines  on  is  the  same  RAM 
that  is  used  by  DOS  for  the  buffers.  If  you  decide  to  write  a  special  machine 
language  program  into  those  areas,  you  will  have  to  keep  track  of  which  areas 
you  are  using  and  which  areas  you  will  reserve  for  buffers.  There  are  five  pages 
of  memory,  each  of  which  contains  256  bytes. 


Buffer  Memory  Location 

(Hexadecimal) 

#1  300  — 3FF 

#2  400— 4FF 

#3  500  — 5FF 

#4  600— 6FF 

#5  700— 7FF 


It  it  not  advisable  to  use  buffer  #5  because  this  buffer  is  often  used  by 
DOS  for  various  housekeeping  activities.  Although  it  is  not  always  in  use, 
data  placed  there  may  alter  DOS  procedures  or  may  be  written  over  by  DOS. 

The  memory  space  in  buffers  1  through  4  is  used  only  by  the  buffers.  If 
you  haven't  requested  a  buffer,  and  you  know  that  one  has  not  been  opened  by 
the  system,  you  may  use  that  memory  freely.  One  method  is  to  specify  which 
buffers  you  want  when  you  open  a  disk  channel  and  write  your  routines  in  one 
or  two  of  the  buffers  that  are  not  in  use. 

The  information  that  follows  is  not  intended  for  beginning  programmers. 
The  use  of  the  MEMORY-READ,  MEMORY-WRITE,  and  MEMORY- 
EXECUTE  commands  requires  a  thorough  understanding  of  machine  lan- 
guage programming  and  the  Disk  Operating  System. 

MEMORY-WRITE 

To  store  data  into  the  disk  drive  memory,  you  will  need  to  use  the  MEMORY- 
WRITE  command.  Like  POKE  in  BASIC,  this  instruction  puts  whatever 
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data  you  specify  into  any  memory  location  you  want.  Here  is  an  example  of  a 
POKE  statement. 

POKE  768,  255 

There  is  only  one  byte  transferred  with  each  POKE  statement.  The 
MEMORY-WRITE  command  allows  you  to  transfer  up  to  34  bytes  with  a 
single  statement.  To  perform  the  same  operation  using  MEMORY-WRITE, 
you  would  need  to  convert  the  decimal  memory  location  into  a  hexadecimal 
number;  300  is  the  hexadecimal  equivalent  of  decimal  768.  Since  you  can 
transfer  only  one  byte  at  a  time  with  a  POKE  command,  BASIC  always 
knows  how  many  bytes  to  expect.  With  the  MEMORY-WRITE  command, 
you  will  need  to  indicate  how  many  bytes  are  going  to  be  transferred.  In  this 
case,  only  one  byte  is  going  to  be  transferred,  so  the  command  will  be  quite 
short. 

There  are  some  special  constraints  that  must  be  used  with  these  instruc- 
tions since  they  are  actually  just  extensions  of  machine  code. 

1.  The  memory  address  must  be  entered  as  two  bytes — first  low  byte, 
and  then  high  byte. 

2.  All  of  the  data  must  be  transferred  as  character  strings  (CHR$). 

3.  The  6502  understands  only  binary  data.  The  instruction  allows  you  to 
enter  numbers  in  hexadecimal;  but  BASIC  doesn't  use  that  notation. 
For  instance 

65536  decimal  =  FFFF  hexadecimal 

is  two  hexadecimal  bytes  (FF  and  FF).  To  represent  them  in  this 
mode,  take  the  two  bytes  and  convert  each  to  its  decimal  equivalent, 
255.  The  number  65536  would  then  be  stored  into  the  disk  drive's 
memory  as  CHR$(255)CHR$(255).  Any  number  that  can  be  expressed 
in  only  one  byte  (0  to  255)  must  be  entered  that  way. 

4.  You  must  indicate  how  many  bytes  are  being  transferred.  This  should 
also  be  expressed  as  hexadecimal  numbers  converted  to  decimal 
notation. 

5.  The  MEMORY-WRITE  instruction  must  be  abbreviated  "M-W". 
No  colon  or  other  punctuation  is  allowed. 

The  code,  then,  to  store  255  into  memory  location  768  ($0300)  is  as 
follows: 

OPEN  15,8,15 

PR  I  NT#  1 5 ,  "  M-W  "  CHRi  <  00 )  CHR*  <  03  >  CHR*  < 1 >  CHR*  <  253  > 

CLOSE  15 
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MEMORY-READ 

It  is  possible  to  read  any  memory  location  in  the  1541  and  1571  using  the 
MEMORY-READ  instruction.  This  instruction  allows  you  to  read  one  byte 
at  a  time  from  the  disk  drive  memory,  similar  to  the  way  PEEK  allows  you  to 
read  one  byte  at  a  time  from  the  C-128's  memory. 

The  BASIC  instruction  to  read  memory  location  768  would  be 

PRINT  PEEK < 768) 

The  same  instruction  using  the  MEMORY-READ  instruction  would  look 
like  this. 

40  OPEN  15,8,15 

50  PR I NT# 1 5 , " M-R '» CHR*  < 00  > CHRt < 03  > 
60  GET#15,  fl$ 
70  PRINT  fit 
80  CLOSE  15 

This  is  what  happened:  first  you  opened  the  command  (error)  channel 
and  then  requested  the  MEMORY-READ  instruction.  On  the  same  line 
(with  no  additional  punctuation),  the  byte  to  be  read  was  specified  (first  low 
byte,  then  high  byte).  This  is  memory  location  300  hexadecimal — the  same  as 
768  decimal. 

NOTE:  The  instruction  "M-R"  is  the  only  valid  way  to  invoke  this 
instruction.  Spelling  out  the  instruction  will  cause  an  error. 

After  the  data  in  that  location  is  read,  it  can  be  transferred  to  the 
computer  through  the  error  channel  (#  15).  To  read  it  from  the  error  channel, 
the  instruction  GET#  15,  A$  was  used.  The  values  were  then  available  as 
variable  A$,  which  was  printed  to  the  screen.  Finally,  you  closed  the  com- 
mand (error)  channel. 

Since  the  data  read  from  the  1541  or  1571  memory  is  transmitted  through 
the  error  channel,  you  should  not  try  to  read  an  error  condition  from  the  error 
channel  again  until  you  have  closed  it  and  reopened  it.  If  you  do  not  do  this, 
you  will  get  the  data  that  was  transmitted  instead  of  the  error  message. 

MEMORY-EXECUTE 

The  MEMORY-EXECUTE  instruction  is  used  to  run  a  machine  language 
program  that  has  been  entered  into  the  disk  drive's  memory.  The  program 
must  end  with  an  RTS  instruction  so  that  the  processor  will  return  control  to 
the  C-128;  otherwise  the  disk  drive's  internal  memory  will  probably  go  into  an 
endless  loop  —  if  not  worse. 

The  format  of  the  MEMORY-EXECUTE  (M-E)  instruction  is  essen- 
tially the  same  as  that  of  the  MEMORY-READ  instruction. 
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40  OPEN  15,8,15 

50  PRINT#15,  MM-E'THR*<00)CHR*<03> 
60  CLOSE  15 

This  sequence  will  send  the  DOS  into  a  routine  that  begins  at  the  disk  drive's 
memory  location  300  (768  decimal). 

USER  COMMANDS 

The  1541  and  1571  make  use  of  a  number  of  commands  called  user  com- 
mands. (Do  not  mistake  these  for  USR  routines,  which  are  a  part  of  BASIC.) 
These  commands  perform  a  number  of  convenient  functions  that  are  similar 
to  the  other  commands  in  this  section. 

U1 

The  U  l  command  is  similar  to  BLOCK-READ.  In  fact,  its  format  is  identical. 
Look  at  the  BLOCK-READ  command.  B-R  is  simply  replaced  with  U  l .  The 
B-R  command  reads  only  the  data  in  a  particular  block  (sector).  The  Ul 
command  reads  all  the  information  in  the  block,  including  the  two  bytes  that 
precede  the  254  data  bytes.  These  bytes  contain  the  link  to  the  next  block.  The 
link  is  the  track  and  sector  to  go  to  next. 

U2 

The  U2  command  is  similar  to  BLOCK-WRITE.  The  format  of  the  U2 
command  is  identical  to  that  of  B-W.  The  difference  between  these  two 
commands  is  that  invoking  B-W  terminates  the  file:  that  is,  the  track  and 
sector  link  (the  two  bytes  that  precede  the  254  bytes  of  data  in  the  block)  are 
set  to  indicate  that  this  block  is  the  end  of  a  file.  The  next  track  and  sector  are 
not  pointed  to. 

Obviously,  this  can  cause  some  problems.  If,  for  instance,  you  wanted  to 
write  some  data  into  the  middle  of  some  existing  data,  using  the  B-W 
instruction  would  end  the  file  in  the  middle.  U2,  however,  would  not.  It  allows 
you  to  write  in  the  next  track  and  sector  or  to  leave  it  the  same. 

U3-U9 

The  next  few  user  commands  are  similar  to  the  MEMORY-EXECUTE 
command.  They  jump  to  a  specific  location  in  memory  and  begin  executing  at 
that  location.  The  locations  they  jump  to  are  listed  in  Table  8-3. 


PERIPHERAL  DEVICES  311 


The  syntax  for  the  U3  command,  for  example,  is 

OPEN  15,8,15 
PRINT#15,  "U3:,f 
CLOSE  15 

The  command  U:  (or  UJ)  will  jump  the  DOS  to  its  power-up  routine. 
The  locations  that  the  user  commands  jump  to  are  only  three  bytes  long 
because  they  are  intended  to  contain  a  JMP  machine  code  instruction  to  go  to 
a  program  that  you  define. 

THE  MODEM 

The  modem  allows  your  C-128  computer  to  communicate  with  other  comput- 
ers over  telephone  lines.  This  will  allow  your  C-128  to  talk  to  other  C-128s 
directly  and  to  access  the  various  computer  networks.  This  means  you  can  use 
your  C-128  as  a  terminal  to  a  large  mainframe  computer  somewhere  in  the 
network.  The  networks  give  you  access  to  information  such  as  stock  market 
reports,  articles  from  a  variety  of  publications,  airline  schedules,  and  mes- 
sages from  other  computer  users. 

Installing  the  Modem 

To  install  the  modem,  perform  the  steps: 

1.  Turn  OFF  the  power  to  your  C-128. 

2.  Plug  the  modem  into  the  C-128's  user  port  (see  Figure  1-2). 

3.  Turn  the  C-128  back  ON. 

4.  Load  a  program  to  operate  the  modem. 

5.  Dial  the  appropriate  phone  number  to  reach  either  the  network  you 
wish  to  access  or  the  other  computer  you  are  calling. 

If  you  are  accessing  one  of  the  networks,  you  will  need  to  code  in 
your  ID  and  access  code  numbers  on  the  C-128. 

If  you  are  accessing  another  computer,  you  will  need  to  set  your 
modem  to  "O"  (originate),  and  the  computer  you  are  calling  must  be 
set  to  "A"  (answer). 

6.  When  you  hear  a  high-pitched  tone,  unplug  the  telephone  receiver 
and  plug  the  cord  into  the  modem. 

NOTE:  If  you  have  a  Trimline  telephone,  you  will  need  a  special 
adapter  for  the  modem;  it  will  not  work  with  this  kind  of  telephone 
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because  the  telephone  electronics  are  in  the  handset,  which  you 
unplug  when  you  disconnect  the  cable. 

7.  Put  the  handset  aside.  Do  not  hang  it  up;  this  will  disconnect  the 
modem. 


Terminology 

The  following  is  a  list  of  common  terms  used  in  telecommunications: 


Modem 


Handshaking 

Full/half 
duplex 


Baud 
rate 


Answer/ 
originate 


The  peripheral  device  used  to  convert  the  signals  output 
by  your  computer  into  information  that  can  be  trans- 
mitted over  the  telephone  lines.  {Modem  stands  for 
"mod  ulate  /  demod  ulate . ") 

The  process  of  sending  data  and  waiting  for  an  acknowl- 
edgment from  the  receiving  computer. 

These  are  two  modes  of  handshaking.  In  full  duplex 
mode,  a  computer  sends  some  data  and  the  receiving 
computer  repeats  the  data  back  to  the  originating  com- 
puter. If  the  data  returned  is  the  same  as  that  sent,  the 
originating  computer  sends  the  next  byte.  If  it  is  incor- 
rect, the  data  is  sent  again.  In  half  duplex  mode,  the 
originating  computer  sends  data  and  the  receiving  com- 
puter simply  acknowledges  that  the  data  has  been  received. 

This  indicates  the  maximum  speed  at  which  data  is 
transmitted  and  received.  The  VIC  Modem  sends  and 
receives  data  at  300  baud.  Another  way  of  describing 
baud  rate  is  in  BPS,  or  bits  per  second.  A  system  run- 
ning at  300  baud  will  send  or  receive  300  bits  of  data 
per  second. 

When  you  connect  to  one  of  the  networks,  you  will  be 
calling  the  system.  Since  you  are  originating  the  call, 
your  modem  should  be  set  to  "originate."  This  sets  up 
the  "introductory"  protocol  in  the  electronics.  If  you  are 
communicating  directly  with  another  computer,  one 
computer  must  be  in  originate  mode  and  the  other  in 
answer  mode.  After  communications  have  been  estab- 
lished, it  makes  no  difference  which  is  which. 


Parity 


Word  length 

Start  I  stop 
bits 


Linefeed 


ASCII 


In  order  to  verify  that  the  data  transmitted  is  correct, 
some  computers  will  send  an  extra  bit  called  the  parity 
bit  along  with  the  data.  If  the  total  of  all  the  ON  (or  1) 
bits,  including  the  parity  bit,  is  an  even  number,  the 
transmission  is  odd  parity.  If  the  parity  bit  is  missing, 
the  transmission  has  no  parity.  To  communicate  prop- 
erly, both  computers  must  be  set  to  the  same  parity. 

This  is  the  number  of  bits  in  each  byte.  Most  computers 
use  a  word  length  of  seven  or  eight  bits. 

Some  computers  require  that  a  certain  number  of  null 
bits  be  transmitted  after  each  byte.  These  null  bits  are 
called  stop  bits.  If  the  system  uses  these,  the  most  com- 
mon number  is  one  stop  bit  and  one  start  bit.  If  this  is 
the  case,  the  total  number  of  bits  per  byte  increases  to 
ten.  This  will  slow  the  effective  transmission  rate 
slightly,  but  will  not  impair  the  operation  of  the  C- 128  or 
the  modem. 

At  the  end  of  a  line  of  data,  the  computer  will  typically 
send  a  carriage  return.  Some  systems  also  require  a  line 
feed  after  each  line  or  data  file. 

This  is  the  standard  coding  used  to  communicate 
the  numbers  1  through  9  and  upper-  and  lowercase 
letters.  There  are  also  a  number  of  standard  symbols 
and  special  characters  used  in  the  ASCII  (American 
Standard  Code  for  Information  Interchange)  system. 
The  C-128  uses  an  extension  of  the  ASCII  character  set 
for  its  extended  character  set,  but  should  use  this 
extended  set  only  when  communicating  with  other 
Commodore  computers. 


THE  MPS  803  PRINTER 

The  MPS  803  printer  has  a  built-in  character  set  that  closely  resembles  the 
character  set  of  the  C-128.  It  includes  upper-  and  lowercase  letters,  numbers, 
and  graphic  symbols.  You  can  use  the  MPS  803  printer  to  print  fully  pro- 
grammable custom  graphics  of  almost  any  size. 
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OPEN  Statement 

In  order  to  access  the  MPS  803  printer,  you  must  open  a  file  to  it.  The  OPEN 
statement  for  the  printer  has  the  format 

OPEN  fn,  dn,  sa 

where  the  variables  are  defined  as  follows: 

fn  The  file  number  is  the  number  you  choose  to  access  the  file.  You 
may  choose  any  number  between  0  and  255. 

dn  The  device  number  for  the  printer  may  be  either  4  or  5.  This 
number  may  be  selected  using  a  switch  at  the  rear  of  the  printer. 

sa  In  most  cases,  you  will  not  use  a  secondary  address  when  you 
access  the  printer.  The  one  exception  to  this  is  covered  in  the 
section  on  the  printer's  character  sets. 

After  you  have  opened  a  file  to  the  printer,  all  you  need  to  do  to  print  to 
the  printer  is  put  your  data  in  a  PRINT#  statement,  such  as 

PRINT@1,    "YOUR  DATA  GOES  HERE" 

The  printer  will  print 
VOUR  DRTfl  GOES  HERE 

CLOSE  Statement 

After  you  have  finished  accessing  a  file  —  whether  it  is  to  the  printer  or  any 
other  device  —  you  should  always  close  the  file.  To  close  a  file,  you  would  use 
the  following  format: 

CLOSE  file  number 
If  you  opened  a  file  with  a  file  number  of  1 ,  such  as 
OPEN  1,4 

then  you  would  close  with 
CLOSE  1 

CMD  Statement 

Everything  the  C-128  outputs  will  normally  be  sent  to  the  video  display.  The 
video  display  is  known  as  the  primary  output  device.  It  is  possible,  however, 
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to  change  this  to  some  other  device,  such  as  the  printer,  so  you  can  print 
listings  instead  of  merely  looking  at  them  on  the  screen. 

This  is  done  with  the  CMD  instruction.  The  format  of  a  CMD  instruc- 
tion is 

CMD  device  number 

To  instruct  the  C-128  to  use  the  printer  as  the  primary  output  device,  you 
will  first  need  to  OPEN  a  file  to  the  printer. 

OPEN  1,4 

Then  you  can  use  the  CMD  instruction  as  follows: 
CMD  1 

Now  everything  that  the  C-128  would  normally  display  on  the  screen 
will  be  printed  on  the  printer,  including  the  READY  message,  the  display, 
and  error  messages.  Your  entries  will  still  be  displayed  on  the  screen.  To  see 
this,  try  performing  some  PRINT  statements. 

EXITING  THE  CMD  MODE 

There  are  three  ways  to  exit  the  CMD  mode. 

1.  Press  RUN/ STOP  and  RESTORE  at  the  same  time.  This  will  reset  the 
entire  system  and  restore  the  computer  to  its  default  condition. 

2.  Redirect  the  CMD  instruction  to  another  device,  such  as  the  video 
screen,  device  #3. 

CMD  3 

3.  Enter  a  PRINT#  instruction  to  the  primary  device.  For  example,  if 
you  had  made  the  primary  device  #1  with  CMD  1 ,  you  would  exit  this 
mode  with 

PRINT#1 

Of  the  three  methods,  the  last  —  using  a  PRINT#  instruction  —  is  pre- 
ferred because  it  will  exit  the  CMD  mode  and  also  empty  the  printer  buffer. 
Characters  may  have  been  left  there  from  an  incomplete  PRINT  statement 
(one  that  was  terminated  with  a  semicolon). 

The  MPS  803  Printer's 
Character  Sets 

Type  your  name  at  the  C-128's  keyboard.  Press  RETURN  and  type  some  hearts 
(SHIFT-S)  on  the  next  line.  Now  press  the  Commodore  symbol  key  and  SHIFT 
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at  the  same  time.  The  letters  of  your  name  will  become  lowercase  letters  and 
the  hearts  will  become  uppercase  S's. 

Both  the  C-128  and  the  MPS  803  have  two  separate  character  sets 
available,  and  you  can  select  either  set  at  any  time.  There  are  two  ways  to 
select  the  different  character  sets. 

1.  Specify  a  secondary  address  of  7  when  you  OPEN  the  printer  file. 
OPEN  1,4,7 

This  will  select  the  alternate  character  set. 

To  access  the  default  character  set  (the  one  that  is  displayed 
when  you  first  turn  the  C-128  on),  OPEN  your  printer  file  with 

OPEN  1,4 

leaving  out  the  secondary  address. 

2.  Print  the  command  CHR$(14)  for  the  alternate  character  set  or 
CHR$(142)  for  the  standard  character  set,  as  in  the  following 
example: 

10  OPEN  1,4 

20  PR  I  NT#  1 ,  CHR$  (17);"  LOWER  CASE11 
30  PR I NT# 1 , CHR* (145);" UPPER  CASE " 
40  CLOSE  1 

Print  Formatting 

The  comma,  the  semicolon,  and  the  formatting  instructions  tab  and  SPC  help 
you  to  position  data  on  the  video  screen.  Although  the  printer  also  uses  these 
instructions,  it  does  not  treat  them  exactly  as  the  video  display  does. 

THE  COMMA 

The  comma  starts  data  in  two  specific  locations  on  the  video  screen:  col- 
umn 0  and  column  11.  Try  this  example. 

10  FOR  T*0  TO  30 
20  PRINT  T, 
30  NEXT 

Notice  that  two  even  columns  are  displayed,  even  though  the  numbers  in 
them  are  of  different  lengths.  On  the  printer,  a  comma  will  put  11  spaces 
between  your  entries,  but  they  will  not  necessarily  wind  up  in  even  columns. 
Try  the  same  program  on  the  printer. 
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5  OPEN  1,4 

10  FOR  T«0  TO  30 

20  PRINT#1,  T, 

30  NEXT 

40  CLOSE  1 

THE  SEMICOLON 

The  semicolon  operates  in  the  same  way  on  the  printer  as  it  does  on  the 
video  display.  It  is  used  to  separate  variables  without  putting  spaces  between 
them.  Remember,  however,  that  numeric  variables  will  still  be  preceded  by  a 
space  even  with  the  semicolon.  To  see  this,  try  the  following  program: 

10  OPEN  1,4 

20  fl*21    :   B»300  :  flB«57 
30  PRINTtliflJBJflB 

TAB  AND  SPC 

The  TAB  and  SPC  instructions  are  so  similar  that  you  may  often  confuse 
them.  The  TAB  function  designates  an  absolute  position,  and  the  SPC 
function  indicates  a  relative  position.  The  following  TAB  statement  will  print 
an  asterisk  in  column  10  of  the  screen: 

PRINT  TflBC10>;  "Hi" 

Now  try  the  following  statement.  It  will  print  one  asterisk  in  column  10  and 
another  in  column  11. 

PRINT  TflB<10);  "*"  ;TRB<10>;  "Hi" 

The  SPC  instruction  begins  at  the  current  cursor  position  and  counts  the 
indicated  number  of  spaces  over  from  that  point.  Try  the  following  SPC 
statement: 

PRINT  SPC<10>; "*";SPC<10>; "*" 

Although  this  line  looks  almost  identical  to  the  TAB  statement,  it  prints  one 
asterisk  in  column  10  and  another  in  column  21.  This  happens  because  the 
SPC  function  starts  counting  at  the  space  immediately  after  the  first  asterisk 
(column  11)  and  puts  the  next  asterisk  ten  spaces  away. 

USING  POS  TO  TAB  THE  PRINTER 

When  used  in  PRINT#  statements,  TAB  and  SPC  both  act  like  SPC. 
However,  TAB  and  SPC  cannot  appear  directly  after  PRINT#  (for  example, 
PRINT#1,TAB(20)). 
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To  take  a  look  at  these  two  functions,  first  open  the  printer  file  with 

OPEN  1,4 

Now  type  in  the  following  line: 

PRINT#1  , "  "SPCC  10)  i  "*"  j  SPCC  10) ;  »*'■ 

This  will  print  one  asterisk  in  column  10  and  another  in  column  21  on  the 
printer. 

If  you  replace  the  SPC  instruction  with  TAB,  you  will  get  exactly  the 
same  results.  Try  the  following  example: 

PRINT#1 ,     ; TflBC  10) ; »»*" ; TflBC  10) ;  "#" 

To  produce  the  TAB  function  on  the  printer,  you  will  need  to  use  the  POS 
instruction.  POS  is  sent  to  the  printer  as  CHR$(16).  Try  the  following 
example: 

PRINTil  j  CHR*<  16) ;  "10*" ;  CHR*< 16)  J  "  10*" 

CHR$(16)  is  the  POS  instruction.  When  the  printer  encounters  this  com- 
mand, it  uses  the  two  characters  immediately  following  the  command  to 
determine  where  on  the  line  to  begin  printing. 

You  can  also  use  the  character  codes  of  the  numbers  to  indicate  the 
position. 

PRINT#1,   CHR*<16);  CHR$<49);  CHR$(48); 
NOTE:  CHR$(49)  is  1  and  CHR$(48)  is  0. 

Printer  Graphics 

The  printer  has  several  different  modes,  which  are  described  in  Table  8-4. 
The  characters  it  receives  will  be  treated  differently  in  each  mode. 

By  using  the  various  modes,  you  can  print  anything  from  standard  text 
to  full  dot  graphics. 

DOUBLE/SINGLE-WIDTH  CHARACTERS 

To  print  double-width  characters  on  the  MPS  803  printer,  use  the 
command  CHR$(14)  before  the  string  you  want  printed. 

PRINTS  ,CHR*<  14);  "THIS  SHOULD  PRINT  WIDE" 

To  return  to  normal  width,  use  the  command  CHR$(15). 

PRINT#1 ,  CHR*<  14) ;  "WIDE" ; CHR:$(  15)  j  "NARROW" 
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TABLE  8-4.  Printer  Modes 


Mode 

Printer  Command 

Print  double-width  characters 
Print  single-width  characters 
Print  reverse  characters 
Print  non-reverse  characters 
Graphics 

Alternate  character  set 
Standard  character  set 
Repeat  graphics 

CHR$(l4) 

CHR$(l5) 

CHR$(l8) 

CHR$(l46) 

CHR$(8) 

CHR$(l7) 

CHR$(l45) 

CHR$(26) 

REVERSE  CHARACTERS 

Reverse  field  characters  can  be  printed  using  the  command  CHR$(l8). 
Try  it  with  this  example. 

PRINT#1,  CHR*<  18);  "REVERSE  CHARACTERS" 

Notice  that  the  command  CHR$(18)  is  the  same  as  the  CHR$  function, 
which  prints  reverse  characters  on  the  video  screen.  On  the  screen,  pressing 
CTRL  and  RVS  ON  together  switches  to  reverse  characters.  This  also  works  on 
the  printer  if  you  put  the  instruction  in  a  PRINT#  statement  like  the 
following: 

PRINT#1,  "<CTRLXRVS  0N>,:  i  "REVERSE  CHARACTERS" 

You  can  use  either  CHR$(146)  or  press  the  CTRL  and  RVS  OFF  keys  to  leave 
reverse  mode. 

GRAPHICS 

The  command  CHR$(8)  causes  the  printer  to  enter  the  graphics  mode. 
Graphics  are  created  by  printing  patterns  of  dots.  For  instance,  a  smiling 
face  could  be  made  up  of  dots  in  the  following  pattern: 
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This  pattern  is  converted  into  a  set  of  numbers  to  be  sent  to  the  printer  as 
follows:  the  rows  (horizontal  dots)  are  each  given  a  numeric  value.  The  top 
row  is  1 ,  the  next  row  down  is  2,  and  so  forth,  with  each  successive  row  being 
double  the  value  of  the  one  above  it.  The  value  of  the  seventh  row  is  64.  Add 
up  the  numbers  in  the  places  that  you  want  to  print  dots.  To  this  number  you 
then  add  128,  and  that  is  the  number  that  you  put  into  the  printer. 

Now,  examine  the  smiling  face  to  determine  what  the  value  of  each  row 
should  be  to  print  it  on  the  printer. 


ABCDE  FGH 


4+  8+  16=  28 
2  4-  8  +  32=  42 
1  +  4+  16  +  64=  85 
1  +  16  +  64=  81 
1  4.  16  +  64=  81 
1  +  4  +  16+  64=  85 
2+8  +  32=42 
4  +  8+  16=  28 


Look  at  column  A.  The  dark  squares  represent  locations  in  which  the 
printer  should  print  dots.  Adding  up  the  values  of  the  locations  in  column  A, 
you  get  4  +  8  +  16  =  28.  Column  B  is  2  +  8  +  32  =  42. 

If  you  continue  through  all  eight  columns,  you  will  get  the  values  28, 42, 
85,81,81,85,42,  and  28. 

To  print  these  as  a  graphic  shape,  put  the  values  into  CHR$  statements, 
such  as  the  following: 

10  DfiTfl  28,42,85,81,81,85,42,28 

20  OPEN  1,4 

30  PRINT#1,  CHR*<S>; 

40  FOR  R*l  TO  8 
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50  READ  A 

60  PRINT#l,CHR*<fl+128); 
70  NEXT 
30  PRINT#1 
90  PRINT#1 

This  will  print  a  smiling  face  on  the  printer.  You  can  print  more  smiling  faces 
by  repeating  this  pattern. 

You  can  also  use  the  function  keys  to  produce  the  special  characters. 
Here's  a  short  program  that  prints  whatever  text  you  enter  into  it,  plus  a 
smiling  face.  The  smiling  face  will  be  printed  (on  the  printer  only  —  an 
asterisk  will  be  printed  on  the  screen)  each  time  you  hit  the  Fl  key. 

10  OPEN  1,4 

20  GET  fl*:   IF  fl*-""  THEN  20 
30  IF  A*  *  "<F1>"  THEN  70 
40  PRINT#1,  fl* 
50  PRINT  fl*j 
60  GOTO  20 

70  DATA  28,42,85,81,81,85,42,28 
80  PRINT#l,CHR*(8>j 
90  FOR  R*l  TO  8 
100  READ  A 

110  PRINT#1,  CHRSCfl+128); 
120  NEXT : PRINT  ••*"; 
130  PRINT#1,  CHR*C15> 
140  RESTORE :  GOTO  20 


GRAPHICS  REPEAT  FUNCTION 

The  graphics  repeat  function  allows  you  to  print  any  pattern  of  seven 
vertical  dots  as  many  times  as  you  like  (up  to  255  times  per  command). 
Here's  an  example  of  a  repeat  function. 

OPEN  1,4 

PR I NT# 1 ,  CHR* <  26  >  CHR*  < 1 0  > CHR*  < 255  > 

This  will  print  a  solid  horizontal  bar  seven  dots  high  by  ten  dots  long. 

CHR$(26)  is  the  repeat  function,  CHR$(10)  is  the  number  of  times  to 
repeat,  and  CHR$F(255)  produces  the  dot  pattern  containing  seven  vertical 
dots. 

This  function  can  easily  be  incorporated  into  the  smiling  face  routine 
given  earlier  and  used  to  expand  the  face. 

10  DATA  28,42,85,81,81,85,42,28 

20  OPEN  1,4 

30  INPUT  "WIDTH" ;W 

40  PRINT#1,CHR*<8); 

50  FOR  R-l  TO  8 
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60  READ  fl 

70  PRINT#1,CHR*<26>  CHR*(W)  CHR*<fl+128)J 
80  NEXT 
90  PRINT#1 

Put  different  values  into  the  width  variable  when  the  program  requests  it 
and  notice  how  the  picture  changes.  Of  course,  this  becomes  impractical  at 
some  point,  since  it  can  become  so  wide  that  it  is  no  longer  recognizable. 


CHAPTER 


Machine  Language 
Programming 


9 


BASIC  7.0,  the  version  of  BASIC  that  Commodore  has  built  into  the  C-128,  is 
the  largest  and  most  powerful  BASIC  that  has  ever  been  included  with  a 
Commodore  computer.  However,  even  a  powerful  BASIC  can  sometimes  be 
not  quite  fast  enough  for  certain  kinds  of  programming  operations.  To 
compensate  for  this,  Commodore  has  included  a  machine  language  monitor 
and  mini-assembler/ disassembler.  These  allow  you  to  write  programs  in 
either  BASIC  or  machine  language  (or  assembly  language)  and  mix  the 
programs  as  you  wish,  switching  from  BASIC  to  machine  language  and  back 
again. 

Like  BASIC,  the  machine  language  monitor  is  a  programming  tool.  It 
allows  you  access  to  the  internal  C-128  assembler.  This  chapter  will  look  at 
how  the  monitor  and  assembler  work,  and  how  you  can  write  your  own 
machine  language  programs. 

NOTE:  This  chapter  is  not  a  tutorial  on  machine  language  or  assembly 
language  programming.  It  is  a  guide  to  using  the  monitor  and  mini-assembler 
programs  that  have  been  included  with  the  C-128. 
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THE  MONITOR 

When  you  write  programs  in  BASIC,  you  are  not  actually  writing  commands 
that  the  8502  (the  C-128's  microprocessor)  can  understand  directly.  The  8502 
cannot  really  understand  BASIC.  The  BASIC  instructions  that  you  enter  into 
the  computer  are  translated  into  machine  language  instructions  (which  the 
8502  can  understand)  one  at  a  time  as  they  are  executed.  As  a  result  of  this 
translation,  the  C-128  takes  much  longer  to  run  BASIC  programs  than  it 
takes  to  run  the  actual  machine  language  programs. 

If  this  is  true,  then  why  are  programs  written  in  BASIC?  The  answer  is 
simple.  While  computers  can  understand  and  interpret  the  l's  and  O's  of 
machine  language  very  quickly,  people  cannot.  Since  the  computer  is  sup- 
posed to  be  a  tool  for  people,  it  does  all  of  the  work,  translating  a  language 
that  people  can  understand  (such  as  BASIC)  into  one  that  it  can  understand 
(machine  language). 

BASIC  is  called  a  high-level  language  because  BASIC  is  quite  a  bit  like 
the  English  language.  It  is  usually  easy  to  program  in  high-level  languages 
because  the  instructions  are  fairly  complete  and  perform  whole  tasks.  For 
example,  the  command  PRINT  "HELLO"  translates  the  characters 
"HELLO"  into  binary  numbers  and  sends  them  to  the  video  display.  In 
machine  language,  there  are  quite  a  few  steps  involved,  such  as  interpreting 
the  command  itself,  putting  the  text  into  various  memory  registers,  and  then 
finally  telling  the  video  display  circuits  to  read  the  text  from  the  filled 
memory  locations. 

You  may  recall  two  commands  in  BASIC  that  were  used  earlier  to  look  at 
and  change  the  contents  of  memory.  These  are  PEEK  (read  a  memory 
location)  and  POKE  (write  to  a  memory  location).  Whenever  you  PEEK  a 
memory  location,  the  computer  returns  a  decimal  number.  This  does  not 
mean  that  the  memory  location  is  actually  loaded  with  decimal  numbers.  In 
fact,  the  PEEK  command  utilizes  a  translation  routine  that  converts  the 
binary  (base  two)  numbers  in  memory  into  decimal  numbers  when  it  displays 
them. 

Getting  Started 

The  monitor  is  not  actually  a  programming  language.  Although  it  can 
manipulate  the  computer's  memory  and  you  can  use  it  to  write  routines,  it 
would  be  difficult  to  write  a  complex  program  with  the  monitor  because  it 


MACHINE  LANGUAGE  PROGRAMMING  325 


does  not  understand  or  create  any  instructions  directly.  Writing  a  program 
with  the  monitor  would  be  like  writing  programs  using  POKEs  in  BASIC. 

Before  you  begin  writing  assembly  language  programs,  you  must  enter 
the  monitor.  The  BASIC  command  that  does  this  is  MONITOR.  When  you 
first  enter  the  monitor,  you  will  see  two  lines  of  code.  The  top  line  shows  the 
names  of  the  8502  registers.  The  second  line  displays  the  values  in  each  of  the 
registers. 

MONITOR 

PC  SR  AC   XR  YR  SP 

;      FBOOO  00  00  00  00  FS 

NOTE:  If  you  need  additional  information  on  these  registers  or  any 
facet  of  machine  or  assembly  language  programming,  read  6502  Assembly 
Language  Programming,  2nd  edition  (Berkeley:  Osborne/ McGraw-Hill, 
1986)  by  Lance  Leventhal.  The  6502  and  8502  microprocessors  use  the  same 
commands. 

Numbers 

There  are  actually  four  types  of  numbers  that  may  be  used  in  this  machine 
language  monitor:  binary,  octal,  decimal,  and  hexadecimal.  These  are  base  2, 
base  8,  base  10,  and  base  16. 

The  C-128  monitor  can  translate  between  these  number  types  for  you. 
The  default  number  system  used  in  the  monitor  is  hexadecimal.  If  you  wish  to 
enter  a  number  in  a  different  base,  precede  the  number  with 

+  for  decimal  numbers 
&  for  octal  numbers 
%  for  binary  numbers. 

You  may  optionally  precede  a  number  with  $,  which  designates  hexadecimal; 
however,  a  nonprefixed  number  is  assumed  to  be  hexadecimal. 

There  are  14  monitor  commands,  which  are  outlined  in  Table  9-1 .  To  run 
any  of  the  monitor  commands,  simply  enter  the  one-letter  command  and  any 
necessary  parameters.  For  example,  to  begin  assembling  a  program,  type  A 
(to  assemble),  the  starting  address  for  your  program,  and  then  the  assembly 
language  commands.  From  that  point  on,  the  assembler  will  keep  track  of  the 
address  count  for  you  and  will  structure  the  commands  for  you  as  you  enter 
them. 

Table  9-2  lists  all  of  the  8502  instruction  codes  (mnemonics). 
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TABLE  9-1.  The  Monitor  Commands 


COMMAND 

DESCRIPTION 

A 

ASSEMBLE:  Starts  writing  an  assembly  language  program. 

C 

COMPARE:  Compares  two  different  blocks  of  memory. 

D 

DISASSEMBLE:  Translates  a  block  of  coded  memory  into  its 
assembly  language  codes. 

F 

FILL:  Loads  a  block  of  memory  with  a  particular  value. 

G 

GO:  Starts  running  a  machine  language  program  at  a  selected 
memory  location. 

H 

HUNT:  Searches  memory  for  a  specified  pattern  of  numbers. 

J 

JUMP:  Runs  a  subroutine. 

L 

LOAD:  Reads  a  file  from  disk  or  tape  and  loads  it  into  memory. 

M 

\4F\/fORV*   RpaHs  a  HlnpW  nf  mpmnrv  anH  tran<:1atp<i  it  itn  its 

hexadecimal  values. 

R 

REGISTERS:  Displays  the  microprocessor  control  registers. 

S 

SAVE:  Saves  a  copy  of  a  block  of  memory  on  disk  or  tape. 

T 

TRANSFER:  Moves  a  block  of  data  from  one  part  of  memory  to 
another. 

V 

VERIFY:  Compares  a  block  of  data  in  memory  with  a  disk  or  tape 
file. 

E 

EXIT:  Returns  you  to  C-128  mode. 

TABLE  9-2.  A  Summary  of  the  8502  Instruction  Set 


Type 

Instruction 

Object  Code 

Bytes 

Status 

Operation  Performed 

S 

V 

D 

z 

c 

LDA 

Load  Accumulator  from  memory 

addr 

A5  pp 

2 

X 

X 

A— [addr] 

Zero  page  direct 

addr,X 

B5  pp 

2 

X 

X 

A— [addr+X] 

Zero  page  indexed 

(addr.X) 

A1  pp 

2 

X 

X 

A— [[addr+X]] 

Pre-indexed  indirect 

(addr).Y 

B1  pp 

2 

X 

X 

A— [[addr+1.addr]+Y] 

Post-indexed  indirect 

addr16 

AD  ppqq 

3 

x 

x 

A— [addrl  6] 

Extended  direct 

addr16,X  or  Y 

1  101 1x01  ppqq 

3 

X 

X 

A— [addrl  6+X]  or  A— [addrl  6+Y] 

Absolute  indexed 

STA 

Store  Accumulator  to  memory 

S 

addr 

85  pp 

2 

[addrl— A 

Zero  page  direct 

O 

c 

addr.X 

95  pp 

2 

[addr+X]  —  A 

Zero  page  indexed 

0 

(addr.X) 

81  pp 

2 

[[addr  +  X]]  —  A 

Pre-indexed  indirect 

® 
c 

(addr),Y 

91  pp 

2 

[[addr+1,addr]  +  Y]— A 

Post-indexed  direct 

addrl  6 

8D  ppqq 

3 

[addrl  6]— A 

Extended  direct 

o 
E 

S 

addr16,X  or  Y 

10011x01  ppqq 

3 

[addrl  6+X]— A  or  [addrl  6+Y]— A 

Absolute  indexed 

> 

LDX 

Load  Index  Register  X  from  memory 

Index  through  Register  Y  only 

a 

E. 

addr 

A6  pp 

2 

X 

X 

X— [addr] 

Zero  page  direct 

Q. 

addr.Y 

B6  pp 

2 

X 

X 

X— [addr+Y] 

Zero  page  indexed 

TJ 

addrl 6 

AE  ppqq 

3 

X 

X 

X— [addrl  6] 

Extended  direct 

C 
O 

addrl  6,Y 

BE  ppqq 

3 

X 

X 

X— [addrl  6  +  Y] 

Absolute  indexed 

STX 

Store  Index  Register  X  to  memory  Index  through  Register  Y  only 

addr 

86  pp 

2 

[addr]— X 

Zero  page  direct 

addr,Y 

96  pp 

2 

[addr+Y]—  X 

Zero  page  indexed 

addrl 6 

8E  ppqq 

3 

[addrl  6]— X 

Extended  direct 

LDY 

Load  Index  Register  Y  from  memory 

Index  through  Register  X  only 

addr 

A4  pp 

2 

X 

X 

Y— [addr] 

Zero  page  direct 

addr,X 

B4  pp 

2 

X 

X 

Y— [addr+X] 

Zero  page  indexed 

addrl  6 

AC  ppqq 

3 

X 

X 

Y— [addrl  6] 

Extended  direct 

addrl  6,X 

BC  ppqq 

3 

X 

X 

Y— [addrl  6+X] 

Absolute  indexed 

TABLE  9-2.  A  Summary  of  the  8502  Instruction  Set  (continued) 


Type 

Instruction 

Object  Code 

Bytes 

Status 

Operation  Performed 

S 

V 

D 

1 

Z 

c 

I/O  and  Primary  Memory 
Reference  (Continued) 

STY 
addr 
addr,X 
addr16 

84  pp 
94  pp 
8C  ppqq 

2 
2 
3 

Store  Index  Register  Y  to  memory.  Index  through  Register  X  only. 
[addrl^Y                                                      Zero  page  direct 
[addr+X]— Y                                                 Zero  page  indexed 
[addrl  6]— Y                                                  Extended  direct 

ADC 

Add  contents  of  memory  location,  with  carry,  to  those  of  Accumulator. 

addr 

65  pp 

2 

X 

X 

X 

X 

A^A+[addr]  +  C                                             Zero  page  direct 

o 

addr,X 

75  pp 

2 

X 

X 

X 

X 

A^A  +  [addr+X]  +  C                                         Zero  page  indexed 

2 

(addr.X) 

61  pp 

2 

X 

X 

X 

X 

A^A+[[addr+X]]  +  C                                         Pre-indexed  indirect 

9 

a. 

(addr),Y 

71  PP 

2 

X 

X 

X 

X 

A^A+[[addr+1,  addr]+Y]  +  C                             Post-indexed  indirect 

O 
> 

addr16 

6D  ppqq 

3 

X 

X 

X 

X 

A— A+[addr16]  +  C                                           Extended  direct 

o 
E 

addrl  6,X  or  Y 

01111x01  ppqq 

3 

X 

X 

X 

X 

A^A  +  [addr1  6+X]  +  C  or  A«— A+[addr1  6+Y]  +  C    Absolute  indexed 

a> 
I 

(Zero  flag  is  not  valid  in  Decimal  Mode). 

a> 
o 
c 

AND 

AND  contents  of  Accumulator  with  those  of  memory  location. 

s 

addr 

nn 

2 

X 

X 

A- — AA[addr]                                                 Zero  page  direct 

• 

addr,X 

35  pp 

2 

X 

X 

A^A  A  [addr+X]                                             Zero  page  indexed 

> 

(addrrX) 

21  pp 

2 

X 

X 

A^AA[[addr+X]]                                             Pre-indexed  indirect 

o 

(addr),Y 

31  pp 

2 

X 

X 

A— AA[[addr+1,  addr]+Y]                               Post-indexed  indirect 

E 
a> 

addr16 

2D  ppqq 

3 

X 

X 

A— A  A  [addrl  6]                                             Extended  direct 

> 

addr16,X  or  Y 

00111x01  ppqq 

3 

X 

X 

A— AA[addr1 6  +  X]  or  A«— A A[addr1 6+Y]           Absolute  indexed 

onda 

BIT 

AND  contents  of  Accumulator  with  those  of  memory  location.  Only  the  status 

U 

o 

bits  are  affected. 

(0 

addr 

24  pp 

2 

7 

6 

X 

A  A  [addr]                                                    Zero  page  direct 

addr16 

2C  ppqq 

3 

7 

6 

X 

AA[addr16]                                                    Extended  direct 

TABL£  9-2.  A  Summary  of  the  8502  Instruction  Set  (continued) 


Type 


Instruction 

Object  Code 

Bytes 

Status 

Operation  Performed 

S 

V 

D 

1 

z 

c 

CMP 

Compare  contents  of  Accumulator  with  those  of  memory  location.  Only 

status  bits  are  affected. 

addr 

C5  pp 

2 

X 

X 

X 

A-[addr]                                                    Zero  page  direct 

addr,X 

D5  pp 

2 

X 

X 

X 

A-[addr+X]                                               Zero  page  indexed 

(addr,X) 

C1  pp 

2 

x 

x 

x 

A-[[addr+X]]                                              Pre-indexed  indirect 

(addr),Y 

D1  pp 

2 

x 

x 

x 

A-[[addr+1,  addr]+Y]                                  Post-indexed  indirect 

addrl  6 

CD  DDaa 

3 

X 

X 

X 

A— [addrl  6]                                                Extended  direct 

addrl  6,X  or  Y 

11011x01  ppqq 

3 

X 

X 

X 

A-[addr16+X]  or  A-[addr16  +  Y]                   Absolute  indexed 

EOR 

Exclusive-OR  contents  of  Accumulator  with  those  of  memory  location. 

addr 

45 

2 

x 

X 

A* — A-V-[addr]                                              Zero  page  direct 

addr  X 

55  PP 

2 

x 

X 

A* — A-^4addr+X]                                          Zero  page  indexed 

41  ^ 

2 

x 

x 

A« — A-V-[[addr+X]]                                          Pre-indexed  indirect 

(addr),Y 

51  PP 

2 

x 

x 

A« — A-V-[[addr+ 1 ,  addr]+Y]                             Post-indexed  indirect 

addrl  6 

4D  DDaa 

3 

X 

X 

A— A-V-[addr1  6]                                          Extended  direct 

addrl  6, X  or  Y 

0101 1 x01  ppqq 

3 

X 

X 

A^A-^addr16+X]  or  A— A-¥{addr1 6+Y]        Absolute  indexed 

ORA 

OR  contents  of  Accumulator  with  those  of  memory  location. 

addr 

05  pp 

2 

X 

X 

A^AV[addr]                                               Zero  page  direct 

addr,X 

15  pp 

2 

X 

X 

A^AV[addr+X]                                           Zero  page  indexed 

(addr,X) 

01  pp 

2 

X 

X 

A^AV[[addr+X]]                                         Pre-indexed  indirect 

(addr),Y 

11  pp 

2 

X 

X 

A— AV[[addr+1 ,  addr]+Y]                             Post-indexed  indirect 

addrl  6 

0D  ppqq 

3 

X 

X 

A— AV[addr1  6]                                           Extended  direct 

addrl  6,X  or  Y 

0001 1x01  ppqq 

3 

X 

X 

A— AV[addr1  6+X]  or  A— AV[addr1  6+Y]          Absolute  indexed 

TABLE  9-2.  A  Summary  of  the  8502  Instruction  Set  (continued) 


Type 

Instruction 

Object  Code 

Bytes 

Status 

Operation  Performed 

S 

V 

D 

1 

z 

c 

SBC 

Subtract  contents  of  memory  location,  with  borrow,  from  contents  of  Ac- 

cumultor 

addr 

E5  pp 

2 

X 

X 

X 

X 

A  —  A-[addr]-C                                        Zero  page  direct 

addr.X 

F5  pp 

2 

X 

X 

X 

X 

A  —  A-[addr+X]-C                                   Zero  page  indexed 

(addr.X) 

E1  PP 

2 

X 

X 

X 

X 

A  —  A— [[addr+X]]— C                                    Pre-indexed  indirect 

(addr),Y 

F1  pp 

2 

X 

X 

X 

X 

A  —  A-[[addr  +  1  ,addr]  +  Y]-C                         Post-indexed  indirect 

® 
c 

addr  1 6 

ED  ppqq 

3 

X 

X 

X 

X 

A  —  A— [addrl  6]— C                                      Extended  direct 

c 

addrl  6,X  or  Y 

11111  wA1  nnrtrt 

1  I  I  I  I XU 1  PPQQ 

3 

X 

X 

X 

X 

A  —  A-[addr1  6  +  X]-C  or 

o 
o 

A  —  A-[addr1  6  +  Y]-C                          Absolute  indexed 

(Note  that  Carry  value  is  the  complement  of  the  borrow.) 

CO 

cB 
a 

INC 

Increment  contents  of  memory  location  Index  through  Register  X  only 

O 
> 

addr 

E6  pp 

2 

X 

X 

[addr]- — [addr]  +  1                                          Zero  page  direct 

o 

addr,X 

F6  pp 

X 

X 

[addr+X]- — [addr+X]+1                                 Zero  page  indexed 

E 

CD 

addr  1 6 

EE  ppqq 

3 

X 

X 

laudHbr   laddrioj+i                                    extended  direct 

5 

CO 

addrl  6.X 

FE  ppqq 

3 

X 

X 

[addrl  6  +  X]— [addrl  6+X]+1                           Absolute  indexed 

renc 

DEC 

Decrement  contents  of  memory  location.  Index  through  Register  X  only 

C6  pp 

2 

X 

X 

[addr]- — [addr]  — 1                                            Zero  page  direct 

> 

addr  X 

D6  pp 

2 

X 

X 

[addr+X]*  [addr+X]  — 1                                Zero  page  indexed 

o 

addr16 

CE  ppqq 

3 

x 

X 

[addrl  6]— [addrl  61-1                                    Extended  direct 

E 
© 

addrl  6.X 

DE  ppqq 

3 

x 

X 

[addrl  6  +  Xl— [addrl  6  +  X1-1                           Absolute  indexed 

> 

a 

CPX 

Compare  contents  of  X  register  with  those  of  memory  location  Only  the  status 

n 
c 

flags  are  affected 

o 
o 

» 

addr 

E4  pp 

2 

X 

X 

X 

X  — [addr]                                                      Zero  page  direct 

addr  16 

EC  ppqq 

3 

X 

X 

X 

X- [addr  16]                                                  Extended  direct 

CPY 

Compare  contents  of  Y  register  with  those  of  memory  location  Only  the  status 

flags  are  affected 

addr 

C4  pp 

2 

X 

X 

X 

Y-[addr]                                                    Zero  page  direct 

addr  16 

CC  ppqq 

3 

X 

X 

X 

Y-[addr16l                                                  Extended  direct 

TABLE  9-2.  A  Summary  of  the  8502  Instruction  Set  {continued) 


Type 


Object  Code 


Bytes 


S      V      D      I      Z  C 


Operation  Performed 


addr 
addr.X 
addr16 
addr16,X 


addr 
addr.X 
addrl6 
addr16.X 


addr 
addr.X 
addr16 
addr16,X 


26  pp 
36  pp 
2E  ppqq 
3E  ppqq 


66  pp 
76  pp 
6E  pp 
7E  ppqq 


06  pp 
16  pp 
OE  ppqq 
IE  ppqq 


Rotate  contents  of  memory  location  one  bit  left  through  Carry.  Index  through 
Register  X  only. 

[addr] 
[addr+X] 
[addr  16] 
[addr16+X]  • 

L-f~>e|  7 «  0|J 

Rotate  contents  of  memory  location  one  bit  right,  through  Carry.  Index  through 
Register  X  only 

[addr] 
[addr+X] 
[addr16] 
[addr16+X] 


Lt7T-»»]  7  ^TTj-J 

Arithmetic  shift  left  contents  of  memory  location  Index  through  Register  X 

only. 

[addr] 
[addr+X] 
[addr16] 
[addr16+X] 


EM 


TABLE  9-2.  A  Summary  of  the  8502  Instruction  Set  (continued)  J*> 


Type 

Instruction 

Object  Code 

Bytes 

Status 

Operation  Performed 

S 

V 

D 

1 

z 

c 

o 

ry  Memory  Ref. 
Operate)  (Cont.) 

LSR 
addr 
addr,X 
addr16 
addr16.X 

46  pp 
56  pp 
4E  ppqq 
5E  ppqq 

2 
2 
3 
3 

0 
0 
0 
0 

X 
X 
X 
X 

X 
X 
X 
X 

Logical  shift  right  contents  of  memory  location  Index  through  Register  X  only, 
[addr] 
[addr  +  X] 
[addr16] 
[addr16.X] 

128  USER  GUI 

:onda 
mory 

o 

7   ►  0 

o 

m 

LDA  data 
LDX  data 
LDY  data 

A9  pp 
A2  pp 
AO  pp 

2 
2 
2 

X 
X 
X 

X 
X 
X 

Load  Accumulator  with  immediate  data 
A^data 

Load  Index  Register  X  with  immediate  data 
X— data 

Load  Index  Register  Y  with  immediate  data 
Y— data 

Immediate 

TABU  9-2.  A  Summary  of  the  8502  Instruction  Set  {continued) 


Status 

Type 

Instruction 

Object  Code 

Bytes 

Operation  Performed 

V 

1 

z 

c 

ADC  data 

69  pp 

2 

X 

x 

X 

X 

Add  immediate  with  Carry,  to  Accumulator  The  Zero  flag  is  not  valid  in 

Decimal  Mode 

A— A+data+C 

AND  data 

29  pp 

2 

x 

X 

AND  immediate  with  Accumulator 

A*— AAdata 

CMP  data 

C9  pp 

2 

X 

X 

X 

Compare  immediate  with  Accumulator  Only  the  status  flags  are  affected 

<o 

A-data 

<D 

a 

EOR  data 

49  pp 

2 

X 

X 

Exclusive-OR  immediate  with  Accumulator 

O 

A— A  -V-  data 

CO 

ORA  data 

09  pp 

2 

X 

X 

OR  immediate  with  Accumulator 

TJ 
9 

A— A  V  data 

SBC  data 

E9  pp 

2 

X 

X 

X 

X 

Subtract  immediate,  with  borrow,  from  Accumulator. 

A* — A— data— C 

(Note  that  Carry  value  is  the  complement  of  the  borrow  ) 

CPX  data 

E0  pp 

2 

X 

X 

X 

Compare  immediate  with  Index  Register  X.  Only  the  status  flags  are  affected. 

X-data 

CPY  data 

CO  pp 

2 

X 

X 

X 

Compare  immediate  with  Index  Register  Y  Only  the  status  flags  are  affected. 

Y-data 

JMP  label 

4C  ppqq 

3 

Jump  to  new  location,  using  extended  or  indirect  addressing. 

(label) 

6C  ppqq 

3 

PC— label  or  PC— [label] 

ump 

-> 

TABLE  9-2.  A  Summary  of  the  8502  Instruction  Set  {continued) 


G4 

O 


GO 

m 
^3 

Q 

cz 


Type 


Object  Code 


Bytes 


Operation  Performed 


BCC  disp 

90  pp 

BCS  disp 

BO  pp 

BEQ  disp 

FO  pp 

BMI  disp 

30  pp 

BNE  disp 

DO  pp 

BPL  disp 

10  pp 

BVC  disp 

50  pp 

BVS  disp 

70  pp 

Note  the  following  for  all  Branch-on-Condition  instructions: 

If  the  condition  is  satisfied,  the  displacement  is  added  to  the  Program 
Counter  after  the  Program  Counter  has  been  incremented  to  point  to  the  in- 
struction following  the  Branch  instruction. 

Branch  relative  if  Carry  flag  is  cleared 
If  C=0,  then  PC— PC+disp 

Branch  relative  if  Carry  flag  is  set. 
If  C  =  1,  then  PC—  PC  +  disp 

Branch  relative  if  result  is  equal  to  zero. 
If  Z  =  1,  then  PC— PC+disp 

Branch  relative  if  result  is  negative. 
If  S=1,  then  PC— PC  +  disp 

Branch  relative  if  result  is  not  zero. 
If  Z=0,  then  PC— PC+disp 

Branch  relative  if  result  is  positive. 
If  S=0.  then  PC— PC+disp 

Branch  relative  if  Overflow  flag  is  cleared. 
If  V  =  0,  then  PC— PC+disp 

Branch  relative  if  Overflow  flag  is  set. 
If  V=1.  then  PC— PC  +  disp 


TABLE  9-2.  A  Summary  of  the  8502  Instruction  Set  (continued) 


Type 

Instruction 

Object  Code 

Bytes 

Status 

Operation  Performed 

S 

V 

D 

1 

z 

c 

Subroutine  Call  and  Return 

JSR  label 
RTS 

20  ppqq 
60 

3 
1 

Jump  to  subroutine  beginning  at  address  given  in  bytes  2  and  3  of  the  instruc- 
tion Note  that  the  stored  Program  Counter  points  to  the  last  byte  of  the  JSR  in- 
struction 

[SP]— PC(HI) 

[SP-1]  —  PC(LO) 

SP— SP-2 

PC— label 

Return  from  subroutine,  incrementing  Program  Counter  to  point  to  the  instruc- 
tion after  the  JSR  which  called  the  routine 

PC(LO)— [SP  +  1] 

PC(HI)  — [SP  +  2] 

SP— SP  +  2 

PC— PC+1 

TAX 

AA 

X 

X 

Move  Accumulator  contents  to  Index  Register  X. 

8A 

X 

X 

Move  contents  of  Index  Register  X  to  Accumulator 

e 

TAY 

A8 

1 

X 

X 

Move  Accumulator  contents  to  Index  Register  Y 

> 
o 

Y— A 

5 

TYA 

98 

1 

X 

X 

Move  contents  of  Index  Register  Y  to  Accumulator 

<D 

A— Y 

(A 

'5> 

TSX 

BA 

X 

X 

Move  contents  of  Stack  Pointer  to  Index  Register  X 

OC 

X-S° 

TXS 

9A 

Move  contents  of  Index  Register  X  to  Stack  Pointer 

£ 
o 

SP— X 

oc 

TABLE  9-2.  A  Summary  of  the  8502  Instruction  Set  (continued) 


o 

oo 

c: 
go 
m 

CD 

cz 


Type 


Object  Code 


Bytes 


Operation  Performed 


DEX 
DEY 
INX 
INY 
ROL  A 


CA 
88 
E8 
C8 
2A 


Decrement  contents  of  Index  Register  X. 
X— X-1 

Decrement  contents  of  Index  Register  Y. 
Y— Y- 1 

Increment  contents  of  Index  Register  X. 
X— X+1 

Increment  contents  of  Index  Register  Y. 
Y— Y  + 1 

Rotate  contents  of  Accumulator  left  through  Carry. 


Rotate  contents  of  Accumulator  right,  through  Carry 


Arithmetic  shift  left  contents  of  Accumulator 


EH 


Logical  shift  right  contents  of  Accumulator 


J- 


TABLE  9-2.  A  Summary  of  the  8502  Instruction  Set  (continued) 


Type 

Instruction 

Object  Code 

Bytes 

Status 

Operation  Performed 

S 

V 

D 

1 

z 

c 

Stack 

PHA 
PLA 
PHP 
PLP 

48 
68 
08 
28 

1 
1 
1 
1 

X 
X 

X 

X 

X 

X 
X 

X 

Push  Accumulator  contents  onto  Stack 
[SP]-A 
SP— SP-1 

Load  Accumulator  from  top  of  Stack  ("Pull") 

A— [SP+1] 

SP— SP+1 
Push  Status  register  contents  onto  Stack 

[SP]— P 

SP— SP-1 

Load  Status  register  from  top  of  Stack  ("Pull") 
P— [SP  +  1] 
SP— SP+1 

CLI 

58 

1 

0 

Enable  interrupts  by  clearing  interrupt  disable  bit  of  Status  register 

I— 0 

SEI 

78 

1 

1 

Disable  interrupts 
1  —  1 

RTI 

40 

1 

x 

x 

x 

x 

x 

Return  from  interrupt;  restore  Status 

P— [SP+1] 

PC(LO)-[SP  +  2] 

PC(HI)  — [SP  +  3] 

SP— SP+3 

PC— PC  +  1 

BRK 

00 

1 

1 

Programmed  interrupt.  BRK  cannot  be  disabled.  The  Program  Counter  is  incre- 

mented twice  before  it  is  saved  on  the  Stack 

[SP]  —  PC(HI) 

[SP-1]  —  PC(LO) 

[SP-2]-P 

SP— SP-3 

PC(HI)-[FFFF] 

PC(LO)— [FFFE] 
1  —  1 

B— 1 

si 


TABLE  9-2.  A  Summary  of  the  8502  Instruction  Set  (continued) 


Type 

Instruction 

Object  Code 

Bytes 

Status 

Operation  Performed 

S 

V 

D 

1 

z 

c 

Status 

CLC 
SEC 
CLD 
SED 
CLV 

18 
38 
D8 
F8 
B8 

0 

0 
1 

0 

1 

Clear  Carry  flag 

C-0 
Set  Carry  flag 

C-1 

Clear  Decimal  Mode 

D— 0 
Set  Decimal  Mode 

D  — 1 

Clear  Overflow  flag 
V—  0 

NOP 

EA 

No  Operation 

CHAPTER 


Using  C/PM 


10 


Ordinarily  when  you  turn  ON  the  C-128,  it  immediately  takes  you  to  the  C-128 
start-up  screen.  To  make  it  boot  or  start  CP/M,  install  at  least  one  disk  drive 
in  your  system  and  turn  it  ON.  Then  insert  the  CP/M  master  disk  into  the 
drive.  Close  the  drive  door  and  turn  the  C-128  ON.  With  the  CP/  M  disk  in  the 
disk  drive,  the  C-128  will  automatically  boot  CP/M. 

After  CP/M  is  in  the  computer,  it  will  display  a  new  prompt.  Instead  of 
the  flashing  cursor,  CP/M  will  display  the  following: 


Whenever  you  see  this  prompt,  it  means  that  the  computer  is  waiting  for  a 
CP/  M  instruction. 


339 
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NEW  KEYS 


In  addition  to  the  normal  keys  that  you  can  use  in  C-128  mode,  CP/M  has 
some  special  keys  that  it  can  use.  They  are: 

ESC 

Stands  for  escape;  usually  used  to  terminate  an  operation  and  go  back  to 
the  function  that  called  it. 

DEL 

Deletes  one  character  to  the  left  and  moves  the  cursor  one  space  to  the 
left. 

BREAK 

Used  in  communications  programs  to  inform  the  other  computer  (or 
terminal)  that  you  wish  to  "break"  from  what  it  is  currently  doing. 

CURSOR  KEYS 

Cursor  keys  (keys  with  arrows  on  them)  are  used  to  move  the  cursor  in 
the  direction  of  the  arrow. 

FUNCTION 

Special  keys  that  perform  an  operation  or  function,  or  sometimes  type  a 
sequence  of  characters.  A  function  key  is  often  labeled  with  the  function 
it  performs  (if  it  is  fixed),  as  in  INSERT,  DELETE,  JOIN,  HELP,  and  so  on. 

TAB 

Moves  the  cursor  eight  spaces  to  the  right. 


FILES 

CP/M  accesses  and  manipulates  information  stored  on  disks  in  files.  A  file  is 
any  information  stored  as  a  single  entity  and  given  a  unique  name.  The  length 
of  a  file  may  vary  from  no  characters  to  the  maximum  capacity  of  the  disk. 
Here  are  some  examples  of  files: 

•  A  single  program 

•  All  of  the  data  used  by  a  program 

•  An  entire  mailing  list 

•  A  single  list 

•  A  large  group  of  standard  form  letters 

•  A  chapter  of  this  book 
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•  The  entire  contents  of  this  book. 

No  rule  determines  the  information  you  may  store  in  a  file.  You  define  a 
file's  contents  when  you  create  the  file. 

All  files  consist  of  fields:  single  words,  numbers,  or  any  other  conve- 
nient, small  unit  of  information.  You  can  also  divide  files  into  records,  a 
division  of  information  that  is  larger  than  a  field. 

How  files  are  divided  into  records  and  fields  depends  again  on  how  you 
create  the  file.  To  see  the  difference  between  records  and  fields,  consider  a 
mailing  list  file.  All  the  names  and  addresses  may  constitute  a  single  file,  but 
each  name  and  address  can  be  designated  as  a  single  record,  while  the  name 
and  each  line  of  the  address  may  each  become  a  single  field. 

FILE:    C============NAME  AND  ADDRESS  FILE============3 

RECORDS:    C — name/address/city — 3   [ — name/address/city — 3 
FIELDS:    [name]    [address]   Ccity3   [name]    [address]  [city3 


File  Names 

Each  CP/M  file  has  a  unique  name  consisting  of  one  to  eight  characters. 
Normally  only  uppercase  letters  are  used  for  file  names. 

CP/M  automatically  converts  characters  you  type  in  a  command  line 
(following  the  A>)  from  lowercase  to  uppercase  and  will  not  accept  a  blank 
file  name  in  a  command  line.  Several  characters  may  not  be  used  in  a  file 
name.  These  characters  are 

<>.,;:  =  ?*[]()  /  <tab> 

Since  CP/  M  uses  each  of  these  characters  in  special  ways,  they  are  invalid  as 
file  name  characters. 

In  addition,  you  may  not  use  control  characters  (or  any  other  characters 
that  do  not  appear  on  the  screen)  in  a  file  name.  Here  are  some  samples  of 
valid  CP/M  file  names: 

FILENAME 

IS-FILE 

OH! 

87654321 

A+  B+  C  (Not  recommended  since  the  plus  sign  can  be  mis- 

interpreted in  some  instances) 
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The  following  are  invalid  CP/M  file  names: 
ISFILENAME       Too  many  characters 
IS, FILE  Contains  illegal  character 


<FILE> 


Contains  illegal  characters 


IS)FILE 


Contains  illegal  character 


FILEAC 


Contains  control  character 


WORD* 


Contains  illegal  character 


When  you  select  a  name  for  a  file,  it  is  best  to  pick  a  name  that  is 
meaningful  and  obvious.  A  file  containing  the  instructions  for  your  payroll 
program  could  be  called  PAYROLL.  Naming  your  payroll  program  PR  102 
might  make  perfectly  good  sense  to  you,  but  it  is  more  likely  that  you  will 
forget  what  is  in  such  a  file. 

Avoid  the  common  practice  of  shortening  the  file  name  to  save  key- 
strokes. Naming  your  payroll  program  P  to  save  six  letters  may  seem  like  a 
good  idea  at  first,  but  imagine  looking  at  the  contents  listing  of  a  disk  and 
seeing  nothing  but  one-letter  file  names.  If  you  have  a  lot  of  files,  it  may  take 
you  longer  to  figure  out  what  files  are  on  the  disk  than  it  does  to  type  the  extra 
six  letters  in  PAYROLL. 

File  Types 

It  is  a  good  idea  to  identify  files  in  a  manner  that  lets  you  know  what  a  file  is 
going  to  be  used  for,  since  different  types  of  information  are  handled  in 
different  ways.  For  example,  certain  program  file  operations  could  destroy 
the  contents  of  a  data  file  were  it  accessed  by  mistake. 

To  keep  such  disasters  from  happening,  CP/M  relies  upon  a  file  type  to 
express  the  file  function.  The  file  type  follows  the  file  name  and  consists  of  up 
to  three  characters  chosen  from  the  list  of  valid  filename  characters.  The  type 
is  separated  from  the  file  name  by  a  period;  that  is  the  reason  that  a  period 
cannot  be  embedded  within  a  file  name.  When  CP/  M  sees  a  period  in  the  file 
identification,  it  assumes  that  what  follows  is  the  file  type. 

Table  10-1  is  a  listing  of  the  most  common  file  types  you  will  encounter 
using  CP/M.  In  addition,  if  you  use  business-oriented  programs  like  Super- 
Calc,  WordStar,  or  dBASE  II,  you  may  find  files  with  types  such  as  .CAL 
(SuperCalc  data  file)  and  .OVL  or  .OVR  ("overlay"  files). 

While  there  are  other  file  types  in  use,  this  list  represents  about  95%  of 
those  you  will  encounter.  As  you  can  see,  some  types  help  to  identify  particu- 
lar programs.  In  addition,  they  aid  in  selecting  files  to  use  or  to  print. 
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TABl£  10-1.  File  Types  Commonly  Used  by  CP/M 


Type 

Description 

.ASM 

Assembly  language  source  program  file  (CP/  M-80) 

.BAK 

Backup  file 

.BAS 

BASIC  source  program  file 

.CMD 

Directly  executable  transient  program  (CP/  M-86) 

.COM 

Directly  executable  transient  program  (CP/  M-80) 

.DAT 

Data  file 

.DOC 

Document  file  (text  file) 

.HEX 

Intel  HEX  format  object  code  file  (CP/  M-80) 

.INT 

BASIC  intermediate  code  program  file  (CBASIC) 

.LIB 

Library  file 

MAC 

Macro  assembly  language  source  program  file 

.PRL 

Page-relocatable  file  (MP/  M) 

.PRN 

Assembly  language  print  listing  file 

.SUB 

Command  file  for  SUBMIT  program 

.TXT 

Document  file  (text  file) 

.$$$ 

Temporary  file  or  improperly  saved,  unusable  file. 

You  can  also  invent  your  own  file  types.  For  example,  you  might  use  the 
version  number  of  a  program  during  the  development  stages.  If  you  were 
working  on  a  BASIC  program  called  THEBEST,  your  list  of  files  on  a  disk 
might  look  like  this: 

THEBEST.001 
THEBEST.002 
THEBEST.003 
THEBEST.004 
THEBEST.  BAS 

THEBEST.  BAS  represents  the  finished  product,  and  each  of  the  other  types 
represents  the  program  at  a  different  stage  of  development. 

File  types  can  be  one,  two,  or  three  characters  in  length,  or  nonexistent. 
The  file  type  may  sometimes  —  but  not  always — be  omitted  when  you  name  a 
file;  it  depends  on  the  program  you  are  using. 

For  the  most  part,  CP/M  ignores  the  file  type,  but  many  programs 
demand  specific  file  types.  For  example,  the  CBASIC  compiler  requires 
source  program  files  to  have  the  type  of  .BAS,  while  a  CBASIC  compiled 
program  needs  the  type  of  .INT.  But  these  types  are  meaningful  to  the 
CBASIC  program  only;  CP/M-PLUS  knows  nothing  about  the  CBASIC 
program  needs,  and  it  does  not  take  such  needs  into  account  in  any  way. 
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Combining  File  Name 
And  File  Type 

You  can  sometimes  specify  a  file  by  typing  just  the  file  name  (the  eight- 
character  label).  Other  times,  you  must  type  both  the  file  name  and  the  file 
type.  The  file  name  and  file  type  are  always  separated  by  a  period,  so  valid 
examples  of  the  combined  file  name  and  type  are 

WATNOWMY.LUV 
ROBOT.  1 
MICRO.SFT 
THX1138.PIK 
KINDAND.EYE 

Notice  that  eight  characters  are  not  required  in  the  file  name,  nor  are 
three  characters  required  in  the  file  type.  A  file  name  must  have  at  least  one 
character,  though  files  need  not  have  a  type.  In  other  words,  you  may  have 
filenames  of  one  to  eight  characters  in  length  and  file  types  of  zero  to  three 
characters.  All  CP/M  versions  ignore  any  characters  after  the  eighth  one  in  a 
filename  and  the  third  one  in  a  file  type.  Thus,  if  you  type 

CPMUSERGUIDE.BOOK 

when  requested  for  a  file  name  and  type,  CP/M  interprets  this  as 

CPMUSERG.BOO 

In  short,  CP/  M  lops  off  any  character  after  the  eighth  one  in  the  name  and  the 
third  one  in  the  type. 

Now  for  a  caveat:  Computer  language  is  not  standardized  enough  for 
universal  definitions.  For  some  programmers,  the  word  filename  represents 
the  entire  combination  of  file  name,  period,  and  file  type.  Terms  such  as  file 
reference,  file  extension,  primary  name,  and  secondary  name  are  often  used 
to  refer  to  the  various  parts  and  combinations  of  the  file  identification.  In  this 
book,  file  name  describes  the  label  (one  to  eight  characters  in  length)  used  to 
refer  to  the  file,  and  file  type  refers  to  the  function  of  the  file.  In  examples 
where  you  are  to  fill  in  a  specific  file  identification,  the  form 

name  filename. typ 

is  used,  which  would  mean  you  enter  the  command  name,  a  space,  the 
file  name,  a  period,  and  the  file  type.  (Words  in  uppercase  letters  indicate 
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information  that  must  be  typed  exactly  as  shown,  while  lowercase  letters 
indicate  places  where  you  must  substitute  your  data  of  the  type  indicated.) 

Disk  Drive  Identifiers 

CP/M  refers  to  available  disk  drives  with  the  letters  A,  B,  C,  D,  and  so  on.  The 
first,  or  primary,  drive  of  your  system  is  the  A  drive.  Other  drives  follow  in 
alphabetical  order  (for  example,  the  second  drive  is  the  B  drive,  and  so  forth). 
The  only  exception  occurs  when  hard  disk  and  floppy  disk  drives  are  inter- 
mixed on  a  computer  system.  Sometimes  later  letters  (M,  N,  O,  or  P)  are  used 
to  indicate  the  hard  disk  drives  and  early  letters  to  indicate  floppy  drives  (A, 
B,  C,  D,...). 

Since  file  names  also  consist  of  letters,  CP/M  must  distinguish  between  a 
letter  referring  to  a  drive  and  the  same  letter  used  as  part  of  a  command  or  a 
file  name.  To  denote  a  disk  drive,  enter  a  colon  (:)  after  the  drive  letter;  for 
example, 

A: 

In  this  chapter,  A:,  B:,  C:,  and  so  on,  always  pertain  to  disk  drives.  When 
examples  are  provided  that  require  you  to  enter  a  disk  drive  identifier,  they 
will  be  written  as 

command  difilename.  typ 

which  would  indicate  you  are  to  enter  the  command,  a  space,  a  valid  disk 
drive  identifier,  a  colon,  a  file  name,  a  period,  and  a  file  type.  A  disk  drive 
identifier  is  not  required  if  you  want  to  use  the  current  "default"  drive,  the 
drive  that  CP/M  assumes  you  want  to  use  unless  told  otherwise.  (More  about 
default  drives  in  a  moment.) 

If  you  have  used  other  disk  operating  systems,  you  may  have  trouble  with 
the  disk  drive  identifiers;  many  operating  systems  use  numbers  instead  of 
letters  to  identify  drives.  Since  most  manufacturers  do  not  label  the  disk 
drives,  it  makes  sense  for  you  to  place  a  label  with  the  proper  CP/M  identifier 
on  each  drive  in  your  system. 

When  you  start  CP/M,  you  will  almost  always  use  the  A  drive.  Unless 
you  specify  another  drive,  the  A  drive  is  the  default  —  or  currently  logged  — 
drive  for  all  commands  and  programs  you  invoke.  This  means  that  to  use  the 
A  (default)  drive,  you  need  not  type  its  identifier.  If  you  make  the  B  drive  the 
default  (by  typing  B:),  then  all  activity  takes  place  on  the  B  drive  unless  you 
tell  CP/M  otherwise. 
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Wildcard  References 

Sometimes  you  may  not  know  the  name  or  type  of  a  file  you  wish  to  use,  or 
you  may  wish  to  specify  more  than  one  file  at  a  time.  Digital  Research  has 
provided  for  such  occurrences  with  a  set  of  wildcard  references,  sometimes 
called  ambiguous  file  references.  The  asterisk  (*),  when  used  in  a  name  or 
type,  replaces  the  remainder  of  the  file  name  or  file  type  or  both.  The  question 
mark  (?),  when  used  in  a  name  or  type,  replaces  a  single  character  with  the 
name  or  type. 

The  asterisk  (*)  can  represent  the  entire  set  of  characters  on  either  side  of 
the  period  in  a  complete  file  name.  For  instance,  all  of  the  following  are  valid, 
ambiguous  file  specifications  in  CP/M: 

*.BAS  All  files  with  type  of  BAS 

THEBEST*  All  files  with  the  name  of  THEBEST 

*.*  All  files. 

Now  wait  a  minute,  you  may  ask,  what  good  is  that?  Consider  the 
directory  command.  To  learn  the  names  of  all  the  BASIC  programs  on  drive 
A,  type  the  following  command  line  after  the  A>  prompt.  (The  A>  should 
not  by  typed  in.) 

A>DIR. *.BAS 

Here,  DIR  stands  for  directory.  The  computer  displays  all  files  with  the  type 
of  .BAS.  To  erase  all  BASIC  source  program  files  on  the  disk  in  drive  A,  type 

A>ERA  *.BAS 

ERA  stands  for  erase.  The  asterisk  can  be  used  as  the  last  character  in  the 
filename  or  file  type,  in  which  case  it  serves  to  match  any  subsequent  charac- 
ters. An  example  of  this  use  would  be 

A>DIR  T*.BAS 

which  would  display  all  files  of  type  BAS  whose  names  start  with  a  "T." 

You  may  have  already  guessed  that  you  can  use  the  question  mark  as  you 
use  the  asterisk.  For  instance,  if  PROGRAM  1.  ASM  is  the  only  file  with  the 
type  .ASM,  the  following  commands  are  treated  identically  by  CP/M: 

A>ERA  *ASM 

A>ERA  PROGRAM 1 . ASM 

A>ERA   ??"?'?"?? ?1 .  ASM 
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Seven  question  marks  precede  the  1  in  the  last  example  because  the  question 
marks  are  considered  to  occupy  one  character  position  only,  not  several. 
Typing  ?1.ASM  and  ???????1.ASM  is  not  the  same  thing  to  CP/M. 

If  you  have  two  or  more  drives,  you  must  remember  that  CP/M  identifies 
a  disk  drive  with  a  letter  followed  by  a  colon.  The  command 

A  >  D I R  B:*„* 

displays  all  files  on  drive  B.  If  you  did  not  type  B:  in  front  of  the  command,  all 
files  on  drive  A  would  be  displayed  by  default. 

MESSAGES 
FROM  THE  SYSTEM 

CP/M  presents  messages  or  information  on  the  screen  at  some  points.  It  is 
important  to  know  how  to  decipher  these  messages;  otherwise  you  may  find 
yourself  lost  or  not  understanding  the  result  of  a  command  you  type. 

Prompts 

In  CP/M,  a  prompt  is  defined  as  being  something  that  indicates  where  you  are 
to  type  a  command  or  response  to  the  computer.  The  most  common  prompt 
in  CP/M  is  the  command  prompt: 

A> 

This  prompt  provides  information  in  addition  to  showing  you  that  CP/M  is 
waiting  for  a  command.  The  A  in  the  A>  means  that  the  default  disk  drive 
CP/M  uses  (unless  you  tell  it  otherwise)  is  drive  A.  If  you  see 

B> 

CP/M  is  telling  you  that  the  B  drive  is  the  default. 

Under  CP/M-PLUS,  a  number  before  the  drive  letter  in  a  prompt 
indicates  the  "user  area"  you  are  currently  in;  for  example: 

1A> 
5B> 

No  number  in  front  of  the  drive  letter  in  CP/M-PLUS  indicates  that  the 
current  user  area  is  zero. 

B> 
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You  will  read  more  about  user  areas  later.  The  important  factor  here  is  that  a 
number  preceding  a  letter  in  the  CP/M-PLUS  command  prompt  tells  you 
which  user  area  has  been  selected. 

Other  prompts  exist  within  CP/M.  For  instance,  if  you  use  a  program 
called  ED  (short  for  editor),  it  presents  a  prompt  that  looks  like  this: 

The  number  refers  to  the  current  line  number,  while  the  asterisk  is  the  actual 
prompt  (the  earliest  versions  of  CP/M  only  displayed  the  asterisk). 

Other  common  prompts  you  may  encounter  using  CP/  M  are  listed  here. 

Prompt  Meaning 

—  Used  by  the  DDT  program 

#  Used  by  the  SID  program 

*  Used  by  PIP,  ED, 

and  most  Microsoft  programs 

1>  Used  by  SuperCalc 

Used  by  dBASE  II 

Error  and  Advisory  Messages 

Sometimes  CP/M  needs  to  warn  you  about  something  or  inform  you  of  a 
problem.  When  this  happens,  CP/M  displays  an  advisory  or  error  message  on 
your  display. 

Unfortunately,  CP/M's  messages  are  sometimes  confusing  for  new- 
comers to  computing  because  CP/M's  messages  were  designed  to  be  brief  and 
diagnosed  by  computer  experts.  A  typical  CP/M  message  might  look  like 
this 

BDOS  ERR  ON  A:  R/O 

This  would  be  interpreted  as  a  "basic  disk  operating  system  error  encountered 
on  drive  A;  the  disk  was  configured  to  be  read  from  (not  written  to)  only." 
Other  messages  can  be  even  more  confusing: 

CP/M  Error  on  A:    Disk  I/O 

BDOS  Function  =  21  File  =  YORE.FIL 

or 

BIOS  error  writing  drive  A:    crc— error 

(code  =  01/01   -  0100800400070A01 ) N  Retry   this  operation 
(Y  or  N) ? 
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This  section  will  not  attempt  to  explain  everything  these  messages  mean. 
Suffice  it  to  say  that  the  information  CP/M  presents  in  its  messages  is  often 
condensed  or  coded. 

Do  not  press  any  key  until  you  are  sure  that  you  understand  the  message 
CP/M  is  presenting  to  you.  In  some  cases,  the  message  is  presented  to  warn 
you  that  your  action  may  have  some  severe  consequence.  The  effect  is  obvious 
when  the  message  is 

Delete  this  -file? 

but  it  may  not  be  so  obvious  with  other  messages  CP/M  presents. 

SHUTTING  OFF 
THE  SYSTEM 

Earlier  you  learned  how  to  turn  ON  your  computer  system.  The  procedure  for 
shutting  off  the  computer  system  is  not  the  reverse  of  the  power-ON 
procedure. 

First,  use  a  normal  exit  from  any  program  you  might  be  running.  This 
step  is  extremely  important  because  many  programs  do  not  correctly  finish 
writing  information  to  the  disk  until  you  tell  the  program  that  you  are  done. 

Second,  remove  any  disks  from  their  drives.  Then  turn  the  power  OFF  on 
the  disk  drives,  terminal,  printer,  and  any  other  peripheral.  Turn  the  power 
OFF  at  the  microcomputer  last. 

CP/M'S  BUILT-IN 
COMMANDS 

Commands  are  instructions  to  CP/M.  When  CP/M  is  ready  to  receive  a 
command,  it  displays  its  prompt  (usually  A>).  To  get  CP/M  to  perform  a 
command,  you  type  the  command  and  then  press  RETURN. 

All  versions  of  CP/M  have  two  types  of  commands.  They  are  called 
built-in  commands  and  transient  commands.  The  distinction  is  a  subtle  one. 
The  short  programs  that  carry  out  built-in  commands  are  always  present  in 
memory  with  CP/M;  indeed,  they  are  a  part  of  CP/M  itself.  The  programs 
that  carry  out  transient  commands  are  not  automatically  loaded  into  memory 
when  CP/M  is  started  up.  Instead,  issuing  a  transient  command  causes  CP/M 
to  get  a  program  from  the  disk,  load  it  into  computer  memory,  and  then 
execute  the  program.  The  program,  called  a  transient  program,  is  not  present 
in  memory  until  moments  after  you  type  the  command. 
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To  summarize,  here  are  the  definitions  of  a  built-in  command  and  a 
transient  command: 

•  A  built-in  command  is  immediately  executed  by  CP/M  without  con- 
sulting further  instructions  on  disk. 

•  A  transient  command  requires  a  set  of  instructions  stored  on  disk  to  be 
brought  into  memory  before  each  use. 

It  is  important  to  note  that  CP/  M  controls  the  execution  of  all  commands, 
whether  they  are  present  in  memory  or  not.  Both  built-in  and  transient 
command  programs  are  invoked  by  typing  a  command  such  as  LOAD  or 
DIR  in  response  to  the  CP/M  prompt. 

This  distinction  must  be  modified  between  types  of  commands  in  the 
case  of  CP/M-PLUS.  Some  CP/M-PLUS  built-in  commands  are  not  com- 
plete; that  is,  parts  of  the  command  —  normally  the  options  portions  —  are 
stored  on  disk  in  order  to  save  memory  space  within  the  computer.  If  you  type 
DIR  in  CP/M-PLUS,  all  instructions  executed  are  memory-resident;  if  you 
type  DIR[FULL],  directions  are  brought  in  from  disk.  Such  hybrid  com- 
mands will  be  considered  as  built-in  commands  since  they  are  merely  exten- 
sions of  the  built-in  instruction  set. 

Built-in  Commands 
Summary 

Only  six  built-in  commands  are  recognized  by  CP/M-PLUS.  They  are 

CP/M-PLUS 
DIR 
ERA 
REN 
SAVE* 
TYPE 
USER 
d: 

CP/M-PLUS  also  has  the  following  special  control  characters. 


♦CP/M-PLUS's  SAVE  command  is  not  built-in,  but  it  is  covered  here  for  the  sake  of 
continuity. 
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A A  AB  AC  AE  AF  AG  AH  AJ  AK  AM  AP  AQ  AR  AS  AU  AW  AX 

Each  of  these  control-character  commands  is  described  in  detail  later  in 
this  chapter,  but  as  you  can  see,  you  need  to  learn  only  a  few  built-in 
commands. 

Built-in  Commands 
Detailed 

Built-in  commands  have  already  been  briefly  mentioned.  In  the  following 
section,  each  built-in  command  is  described  in  detail. 

DIR 

DIRSYS 

Display  the  System  File 
Directory 

The  DIR  command  displays  a  directory  of  files  on  a  disk.  Several  forms 
of  the  command  are  allowed,  with  CP/M-PLUS  adding  additional  forms.  All 
file  names  can  be  displayed,  disk  directories  may  be  searched  using  the 
wildcard  characters  to  select  a  group  of  similarly  named  files,  or  the  user  may 
specifically  search  for  a  single  file. 

CP/M-PLUS  displays  directories  with  as  many  as  four  files  on  a  line, 
each  separated  with  a  vertical  line 

A > D I R  B: 

B:  DOCUMENT  MAR    !    DOCUMENT  APR    !    DOCUMENT  JUN    !    DOCUMENT  JUL 
B: DOCUMENT  AUG    i    DOCUMENT  SEP 

A> 

CP/M-PLUS  also  shows  additional  information  when  some  of  the 
options  are  chosen  (see  the  subsection  called  "Options").  One  example  of  such 
a  directory  presentation  for  a  standard  CP/M-PLUS  disk  is  the  following: 

A>  DIR  cfull: 


Scanning  Directory... 
Sorting  Directory... 

Directory   -for  Drive  ,a:    User  0 


r 


-Pile  names 
—Kile  sizes 
■f  ile  attributes 


Name 


Bytes 


Recs 


Attributes 


CPM  SYS  18k 

DEVICE  COM  8k 

ED  COM  10k 

HELP  COM  7k 

PIP  COM  9k 

SET  COM  Ilk 

SHOW  COM  9k 

TYPE  COM  3k 


138  Sys  RO 

58  Dir  RW 

73  Dir  RW 

56  Dir  RW 

68  Dir  RW 

81  Dir  RW 

66  Dir  RW 

24  Dir  RW 


Total   Bytes  =  172k 

Total    lk   Blocks  =  172 


Total  Records  =  1315  Files  Found  = 
Used/Max  Dir  Entries  For  Drive  A:  1< 


=  15 
19/64 


A> 


Information  pertaining  to  the  entire  disk 
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Here  are  additional  forms  of  the  directory  command. 
DIR  d: 

Displays  the  directory  of  all  files  present  on  the  drives  specified  (d:). 
The  drive  specification  may  be  omitted,  in  which  case  the  default 
drive  is  used  for  the  search. 

DIR  d: filename. typ 

Displays  the  directory  of  all  files  present  on  the  drive  specified  (d:) 
that  match  the  file  name  and  type  specified.  You  may  use  the 
wildcard  specifiers  *  and  ?  to  search  for  groups  of  files. 

CP/M-PLUS  adds  several  distinct  variations  to  the  DIR  command. 
First,  there  is  the  "system  directory"  command,  DIRSYS  (sometimes  abbre- 
viated as  DIRS),  which  lists  all  files  considered  to  be  system  files  by  CP/  M.  A 
system  file  is  one  that  is  normally  hidden  from  view  of  the  user  (in  other 
words,  normally  used  only  by  the  system,  not  the  user).  In  CPM-PLUS,  the 
actual  CP/  M  program  is  kept  as  a  system  file  (usually  stored  under  the  name 
CPM.SYS).  If  all  system  files  were  shown  when  you  asked  for  a  disk  direc- 
tory, you  would  get  a  cluttered  list  of  files  that  included  ones  that  you  do  not 
normally  use  directly  (that  is,  the  system  files).  By  splitting  the  system  files 
into  a  separate  listing,  you  need  not  confuse  the  files  you  normally  use  with 
those  making  up  the  CP/  M  system.  DIRSYS  works  exactly  like  DIR,  except 
that  it  shows  a  directory  of  only  the  system  files.  Here  are  additional  forms  of 
DIRSYS  and  DIRS. 

DIRSYS  d:  or  DIRS  d: 
DIR  </.[SYS] 

Displays  the  directory  of  all  system  files  present  on  the  drive 
specified  (d:).  The  drive  specification  may  be  omitted,  in  which  case 
the  default  drive  is  used  for  the  search. 

DIRSYS  d: filename. typ  or  DIRS  d: filename. typ 

DIR  d:filename.typ[SYS] 

Displays  the  directory  of  all  system  files  present  on  the  drive 
specified  (d:)  that  match  the  file  name  and  type  specified.  You  may 
use  the  wildcard  specifiers  *  and  ?  to  search  for  groups  of  files. 

You  may  also  include  an  option  list  at  the  end  of  any  directory  command 
(DIR  or  DIRSYS).  Options  are  enclosed  in  one  set  of  square  brackets  ( [  ] )  at 
the  end  of  the  command,  just  prior  to  pressing  RETURN.  A  series  of  options 
may  be  entered  within  the  square  brackets  by  separating  each  with  a  space  or 
comma. 

NOTE:  The  closing  square  bracket  may  be  omitted  if  it  is  the  last  item 
on  a  command  line. 


USING  CP/M  353 


The  format  of  this  command  is  as  follows: 

DIR  d: filename  Ay p  d: filename. typ  . . .  [option] 

DIR  d: filename,  typ  d. filename,  typ  . . .  [option,  option] 

Displays  all  matching  files  using  the  option  or  options  listed.  Note 

that  more  than  one  file  name  and  type  may  be  matched  against; 

each  should  be  separated  by  a  space,  and  a  space  must  precede  the 

start  of  the  options  portion  of  the  command. 

The  available  options  are 
[ATT] 

Displays  the  four  user-definable  attributes. 
[DATE] 

Displays  date  and  time  stamps  for  files,  if  active. 
[DIR] 

Displays  only  files  that  are  in  normal  directory. 

[DRIVE=ALL] 

[DRl\E=(d,d,d)] 

[DRIVER 

Displays  files  on  the  drive  or  drives  specified.  Multiple  drives  may 
be  searched  by  enclosing  a  list  of  them,  separated  by  commas, 
within  parentheses. 

[EXCLUDE] 

Lists  all  files  except  those  matching  the  specified  file  name  and  type. 

[FF] 

Sends  a  form  feed  character  (OC  hex,  12  decimal)  to  the  printer 
before  starting  a  listing,  or,  if  the  printer  is  not  selected  for  output, 
disables  the  paged  display  on  screen  (same  as  [NOPAGE]  if  printer 
is  not  active). 

[FULL] 

Displays  all  information  about  matched  files,  including  file  sizes 
and  attributes. 

[LENGTH=«] 

Displays  n  lines  of  output  before  inserting  a  new  heading  (where  5  < 
n  <  65536).  The  default  is  one  screen  length  (usually  24  lines). 

[MESSAGE] 

Displays  the  names  of  the  specified  drives  and  user  numbers  being 
searched. 
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[NOPAGE] 

Continuously  scrolls  directory  on  the  screen;  does  not  wait  when 
screen  is  filled  with  information. 

[NOSORT] 

Does  not  alphabetize  file  names;  instead,  presents  them  in  the  order 
they  were  found  on  the  disk. 

[RO] 

Displays  only  files  that  have  the  read-only  attribute. 
[RW] 

Displays  only  files  that  have  the  read/ write  attribute. 
[SIZE] 

Displays  the  file  size  in  addition  to  the  file  name. 
[SYS] 

Displays  only  files  with  the  system  file  attribute;  same  as  typing 
DIRSYS  or  DIRS. 

[USER=ALL] 

[USER=(w,w,w)] 

[USER=rc] 

Displays  matching  files  of  the  user  area  or  areas  specified  (where  0 
<  =  w<  =  15). 

NOTE:  You  may  abbreviate  any  option  to  its  first  one  or  two  letters. 
(You  must  type  enough  of  the  option  so  that  CP/M-PLUS  can  figure  out  what 
you  want  —  typing  F  could  stand  for  FF  or  FULL,  so  you  must  type  two 
letters.) 

The  following  are  sample  uses  of  the  CP/M  DIR  command  and  the 
resulting  directories: 

A > DIR  FIV"-.* 

A:  FISH         TRT    !    FISH         BAS    !   FISH         CRP       FISH  ING 
A:  FISH  EEE    ',    FILE  BAS 

A> 

The  command  used  is  DIR  FI??.*,  which  means  "display  all  files  whose 
names  start  with  FI  and  have  any  file  type,  all  on  the  default  drive." 

A  >  DIR 

A:  TEE  COM    !    BEE  COM    !    ECTORY     COM    !    RED  COM 

SYSTEM  FILE(S)  EXIST 

A> 

This  example  shows  a  directory  in  CP/M-PLUS  where  system  files  exist. 
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A: DIRSYS 

A:  REENIE     TWO    !    LIZZIE     ONE    !    MARY  THR    !    EVA  ONE 

A: CARLA  TWO 
NON-SYSTEM  FILE(S)  EXIST 

A> 

The  next  example  shows  a  directory  of  the  system  files  in  CP/M-PLUS 
(note  that  nonsystem  files  —  such  as  directory  files  —  exist). 

This  example  shows  a  directory  where  options  are  requested: 

A > D I R  *.*   CDRIVE=(A,B) , SIZED 
Scanning  Directory... 
Sorting  Directory. . . 
Directory   for  Drive  A:        User  0 

As    WS  COM      16k    !    DS  COM     24k    I    CS  CUM  26k 

A:    SB  COM  38k 

Total   Bytes     =  104k  Total  Records  =       912  Files  Found  =  4 

Total    lk   Blocks  =      104     Used/Max  Dir  Entries   -for  Drive  A:    4/  64 
Directory   -for  Drive  B:      User  0 
NO  FILE  -  *.* 

A> 

You  can  make  several  different  errors  in  using  the  DIR  command.  The 
primary  error  messages  CP/M  might  display  are  listed  here. 

NO  FILE,  NOT  FOUND,  or  FILE  NOT  FOUND 

The  disk  does  not  contain  the  file  you  specified.  Make  sure  that  you 
typed  the  command  correctly;  if  you  did  type  the  command  cor- 
rectly, then  the  file  does  not  exist. 

BDOS  ERR  ON  d: 

CP/M  cannot  find  a  disk  in  the  selected  drive  d:\  the  disk  is 
improperly  formatted,  the  power  to  the  drives  is  OFF,  or  the  drive 
door  has  not  been  closed.  Check  to  make  sure  that  a  disk  is  properly 
inserted  into  the  drive.  If  this  message  is  followed  by  a  BAD 
SECTOR  message,  in  all  probability  you  either  have  a  bad  disk  or 
inserted  the  disk  upside  down. 

DIT? 

Any  error  message  ending  in  a  question  mark  indicates  that  CP/M 
could  not  find  the  command  you  typed.  In  this  particular  instance, 
you  typed  DIT  instead  of  DIR.  Check  carefully  for  typing  errors 
when  you  see  an  error  message  ending  with  a  question  mark. 

ILLEGAL  COMMAND  TAIL 

The  option  list  or  the  format  of  your  directory  command  is  incor- 
rect (CP/M-PLUS  only). 
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ERA 
ERASE 
Erase  a  File 

ERA  stands  for  erase.  To  use  the  command,  you  must  specify  the  file  or 
files  to  be  erased  immediately  after  typing  the  command.  Since  it  is  extremely 
rare  to  remove  all  files  from  a  disk,  CP/M  checks  with  you  to  make  sure  if  you 
ask  it  to  erase  all  files  from  a  disk. 

It  is  good  to  develop  the  habit  of  checking  the  directory  before  invoking 
the  erase  command.  First,  verify  that  the  file  or  files  you  wish  to  remove  from 
the  disk  actually  exist  by  using  the  DIR  command.  Next,  use  the  ERA 
command  to  perform  the  erasure.  Last,  use  DIR  again  to  make  sure  that 
CP/M  correctly  erased  your  selection.  If  you  do  not  use  this  procedure,  you 
will  normally  not  get  any  verification  of  when  and  what  CP/M  erases. 

In  CP/M-PLUS,  the  actual  command  to  erase  a  file  is  ERASE,  not 
ERA.  However,  to  ensure  compatibility  between  CP/M-PLUS  and  earlier 
versions,  you  may  abbreviate  ERASE  to  ERA.  CP/M-PLUS  does  add  one 
option  to  the  standard  CP/M  erase  command:  the  CONFIRM  option.  The 
CONFIRM  option  presents  the  name  of  each  file  to  be  erased  for  user 
verification.  It  is  suggested  that  you  always  use  the  CONFIRM  option  when 
erasing  files.  The  wildcard  characters  *  and  ?  may  be  used  to  specify  more 
than  one  file  at  a  time.  Any  use  of  the  wildcard  characters  results  in  CP/M- 
PLUS  asking  for  a  confirmation  of  the  erasure  request. 

You  may  use  the  standard  CP/M  ERA  command  or  add  the  CONFIRM 
option  to  the  command  format 

ERASE  difilename.typ  [CONFIRM] 

Erases  all  files  that  match  the  file  name  and  type  specified  on  the 
disk  specified  (d:),  but  only  after  the  user  confirms  the  erasure  of 
each  file. 

Here  is  an  example  of  the  ERA  command's  use: 

A>.DIR  C: 

C:    QUALITY     CTL    !    MIND        CTL    !    WEIGHT        CTL    !    THOUGHT  CTL 
A>ERA  C: QUALITY. CTL 
A  >  D I R  C: 

C:    MIND  CTL    !    WEIGHT     CTL    i    THOUGHT  CTL 

A> 

In  this  example  the  user  first  asks  for  a  directory  of  files  on  drive  C;  four  files 
are  listed.  The  user  then  asks  CP/M  to  erase  the  file  named  QUALITY. CTL 
on  drive  C.  Since  no  message  is  presented  to  confirm  this  action,  the  user  asks 
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for  another  directory  to  confirm  the  deletion.  Here  is  another  example: 

A>DIR  B:*.BAS 

B:    NOW  BAS    !    THEN  BAS   !   ALWAYS  BAS 

A>ERA  B:*.BAS 
A>DIR  B:*.BAS 
NOT  FOUND 

A> 

In  this  example,  the  user  finds  three  files  on  the  disk  in  drive  B  with  the  type  of 
BAS,  and  then  asks  CP/M  to  erase  all  files  on  drive  B  with  this  type.  Another 
directory  command  confirms  that  no  files  with  the  type  of  BAS  are  left  on 
drive  B. 

The  next  example  demonstrates  what  happens  when  you  ask  CP/M  to 
erase  all  files  from  a  disk. 

B>DIR 

B:    SOHO      NY      \    CHELSEA       NY      !   UPPREAST  NY    !    UPPRWEST  NY 

B>ERA  *.* 

ALL  FILES  (Y/N)?Y 

B>DIR 

NO  FILE 

B> 

Note  the  message  CONFIRM  (Y/  N)?  If  you  reply  with  anything  other  than  a 
Y  to  the  query,  no  files  are  erased  from  the  disk.  In  this  case,  the  user  replied 
with  a  Y  to  tell  CP/M  to  proceed. 

A > ERASE  TAPE.*  CCONFIRM> 
Erase  A: TAPE       WRM    ( Y/N) ?  Y 
Erase  A: TAPE       MSR    (Y/N) ?  N 
Erase  A: TAFE       URR    (Y/N) ?  Y 
A> 

In  this  example,  the  user  asked  the  computer  to  confirm  each  file  erasure, 
then  proceeded  to  erase  TAPE. WRM  and  TAPE. URR,  but  not  TAPE. MSR. 

The  error  messages  that  you  may  encounter  when  using  the  ERA  com- 
mand are  basically  the  same  as  those  described  with  the  directory  command: 

NO  FILE,  NOT  FOUND,  or  FILE  NOT  FOUND 

CP/M  cannot  find  the  file  name  and  type  you  specified.  For 
instance,  if  you  type  ERA  KNOW  instead  of  ERA  NOW,  this 
message  may  appear.  But  if  you  did  have  a  file  named  KNOW,  it 
would  be  erased!  Do  not  count  on  this  error  message  to  catch  your 
typing  mistakes. 

BDOS  ERR  ON  d: 

CP/  M  cannot  find  a  disk  in  drive  d:\  the  drive  door  is  open,  no  disk 
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has  been  inserted  or  it  has  been  inserted  improperly,  or  the  power  to 
the  drive  has  not  been  turned  ON. 

REN 

RENAME 
Rename  a  File 

Files  may  be  given  new  names  with  the  REN,  or  rename,  command. 
CP/M-PLUS  allows  use  of  the  wildcard  characters  in  renaming  files.  Renam- 
ing files  does  not  make  copies  of  them;  instead,  only  the  name  kept  in  the 
directory  is  changed. 

Almost  universally,  whenever  the  computer  deciphers  an  equivalence 
statement  —  as  in  the  rename  command  —  the  new  formation  or  result  is  to 
the  left  of  an  equal  sign,  and  the  old  formation  or  result  appears  to  the  right. 
This  can  be  expressed  as 

NEW  =  OLD 

A  disk  drive  specifier  can  be  included  with  either  or  both  file  names  when 
you  use  the  rename  command.  If  included  with  one  name,  it  applies  to  both.  If 
included  with  both  file  names,  the  same  drive  specifier  must  be  used  with 
both.  If  omitted,  the  default  disk  drive  is  used. 

You  may  type  either  REN  or  RENAME  under  CP/M-PLUS.  In  addi- 
tion, a  variation  in  which  the  computer  prompts  you  for  information  is 
available.  Here  are  the  two  formats  of  the  REN  command: 

REN  d:new filename.  type=oldfilename.  typ 

REN  new  filename.  typ=d:oldfilename.  typ 

The  rename  command  finds  the  file  of  name  and  type  matching 
oldfilename.typ  on  the  drive  specified  (d:),  and  then  gives  it  the  new 
name  and  type  matching  new  filename. typ. 

NOTE:  You  need  to  indicate  the  drive  on  which  the  renaming  is  being 
performed  only  once  since,  by  definition,  you  cannot  rename  a  file  on  more 
than  one  disk.  Thus,  both  of  these  formats  are  equivalent.  You  may  type  REN 
or  RENAME  in  the  first  part  of  the  command. 

You  may  also  use  the  following  form: 

RENAME 

The  rename  command  prompts  the  user  for  the  name  of  the  file  to 
rename  and  the  new  name  to  associate  with  the  file. 
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Here  is  an  example  of  the  use  of  the  REN  command  as  it  works  in  CP/M 
and  MP/M. 

A>DIR 

A:    HOLDEN       ONE    !    PHOEBE        TWO    !    19EIGHTY  FOR 
A>REN  NOVEL. ONE=HOLDEN. ONE 
A  >  D  J  R 

A:    NOVEL  ONE    !    PHOEBE       TWO    !    19EIGHTY  FOR 

A> 

In  this  example,  the  user  asked  to  change  the  file  named  HOLDEN. ONE  to  a 
file  named  NOVEL. ONE. 

An  example  of  the  RENAME  (prompting  for  names)  version  of  the 
rename  command  looks  like  the  following: 

A > RENAME 

Enter  New  Name:    NOVEL. ONE 
Enter  Old  Name:    HOLDEN. ONE 

File  HOLDEN. ONE   is  renamed  NOVEL. ONE  on   drive  A 

A> 

The  rename  command  has  several  error  messages  associated  with  it: 
NO  FILE 

The  file  you  specified  does  not  exist.  Check  your  typing. 
FILE  EXISTS 

Not  renamed:  filename,  typ  file  already  exists,  delete  (Y/N)? 

BDOS  ERR  ON  d: 

CP/M  could  not  find  the  disk  or  activate  disk  drive  d:.  Check  to 
make  sure  the  disk  is  inserted  properly  and  that  the  disk  drive  is 
powered  ON  with  the  door  correctly  closed. 

TYPE 

Display  a  File  Containing 
ASCII-Coded  Information 

If  you  have  a  file  that  consists  of  printable  characters  —  data,  as  opposed 
to  computer  instructions  —  you  may  display  the  file's  contents  on  your  con- 
sole display  by  using  the  TYPE  command. 

TYPE  usually  works  for  files  with  the  following  types: 

.BAS  .ASM  .BAK  .DAT  .HEX  .DOC  .TXT 
or  any  other  files  that  contain  ASCII  text  or  data.  ASCII  is  a  character 
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recognition  and  storage  scheme  for  computers;  each  character  has  a  unique 
representation  that  can  be  saved  or  used  by  the  computer. 

You  could  also  use  a  text  editor  or  word  processing  program  to  look  at 
the  contents  of  a  file,  but  not  everyone  using  CP/M  has  such  a  program 
available.  Also,  if  you  merely  want  to  take  a  peek  at  your  program  or  data, 
why  go  to  the  trouble  of  using  the  text  editor? 

You  may  use  the  following  forms  of  the  command: 

TYFE  d:filename.typ 

Displays  the  contents  of  the  specified  file. 

TYPE  D filename,  typ  [NO  PAGE] 

Displays  the  contents  of  the  specified  file,  but  lists  the  file  continu- 
ously, as  opposed  to  stopping  every  24  (or  user-specified  number  of) 
lines. 

TYPE  d:filename.typ  [PAGE] 

Displays  the  contents  of  the  specified  file  one  screen  at  a  time;  this  is 
the  default  option,  so  it  need  not  be  explicitly  requested. 

TYPE 

CP/M  prompts  you  for  the  file  name  to  display  with  the  prompt: 

Enter  filename: 

An  example  of  TYPE's  use  would  be 

A>TYPE  O.POS 

Had  Dick  Seeker  been  present,   and  had  he  been  able 
to  see   inside  the  NASCOM  Cray— 1   computer,    he  would 
have  seen  a  string  of  bits  spelling  out  his  name, 
computer  style.      But   the  National   Security  Computer 
Center  was  1500  miles  away;    in   fact,   Dick  wasn't 
even  awar?  of   its  existence. 

In  this  example,  the  user  asked  to  see  a  text  display  of  the  file  O.POS,  and  the 
computer  complied.  If  this  were  a  long  file  —  longer  than  the  console  display 
could  show  at  one  time  —  a  CTRL-S  could  be  pressed  to  temporarily  "pause" 
the  display.  (CP/M-PLUS  requires  a  CTRL-Q  to  resume  displaying  informa- 
tion.) To  terminate  a  text  display  of  a  file,  press  any  key  or  a  CTRL-C. 

filename! 

This  error  message  appears  when  the  file  you  named  does  not  exist 
or  you  misspelled  the  TYPE  command.  Check  your  work  and  try 
again. 

BDOS  ERR  ON  d: 

CP/M  cannot  find  the  disk  or  disk  drive  d:. 
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No  File 

The  file  you  requested  cannot  be  found. 

There  is  one  final  error  situation  that  may  occur,  but  a  message  will  not 
be  displayed.  Instead,  a  meaningless  display,  sometimes  accompanied  by  a 
bell,  will  appear.  This  happens  when  you  try  to  use  TYPE  with  a  file  that  does 
not  contain  ASCII  text  or  that  includes  machine  language  code  within  the 
text.  If  you  accidentally  displayed  a  file  with  machine  language  code  in  it, 
restart  CP/M  to  make  sure  that  you  did  not  also  accidentally  change  the 
contents  of  your  computer's  memory. 

USER 

Change  the  User  Number 

This  command  allows  you  to  specify  a  number  between  0  and  15, 
inclusive,  that  is  to  be  kept  with  any  files  you  create. 

When  you  cold  start  CP/M,  user  number  0  is  assumed.  A  cold  start  starts 
a  system  from  scratch,  destroying  programs  that  were  in  memory  before  the 
cold  start.  A  cold  start  is  often  called  a  cold  boot.  Your  disk  operations  will 
reference  files  in  user  area  0  only.  Therefore,  if  you  save  a  new  file  called 
JUNK.  AGN  after  a  cold  start,  it  will  always  appear  in  directories  assigned  to 
user  area  0.  If  you  type  USER2  before  you  save  the  file,  it  will  appear  only  in 
the  user  area  2  directory. 

"User  areas"  are  imaginary.  Every  file  on  a  disk  has  a  user  number 
associated  with  it,  stored  on  the  disk  as  an  additional  piece  of  information 
about  that  file.  Thus,  it  is  not  necessary  to  set  aside  room  on  the  disk  for  each 
user  area. 

The  USER  command  is  of  minimal  value  in  running  canned  programs 
on  a  floppy  disk  system.  However,  when  several  users  share  disk  drives,  one 
user  can  save  files  in  user  area  1,  another  in  user  area  2,  and  both  can  share 
files  in  user  area  0.  Another  good  use  of  USER  comes  when  you  have  a  hard 
disk  system  with  lots  of  storage  space.  You  might  want  to  put  all  word 
processing  files  in  user  area  1,  data  processing  files  in  user  area  2,  and  so  on. 

When  you  utilize  different  user  areas,  most  commands  function  differ- 
ently. For  example,  typing  ERA*.*  only  erases  all  files  in  the  currently  chosen 
user  number.  There  is  no  way  to  erase  all  files  on  the  disk  with  a  single 
command  unless  they  are  all  in  the  same  user  area. 

Almost  without  exception,  any  disk  you  receive  from  software  vendors 
will  have  all  files  in  user  area  0. 

When  you  are  in  a  user  area  other  than  0,  the  user  number  area  is 
displayed  as  a  prefix  to  the  normal  CP/M  prompt. 
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3A> 
C> 

The  forms  of  the  USER  command  allowed  are 

USER  n  (where  n  is  a  number  between  0  and  15,  inclusive) 
This  establishes  the  user  area  you  wish  to  use. 

USER 

The  system  prompts  you  for  the  user  area  number  to  use. 
?  or  n? 

You  forgot  to  specify  a  number  or  specified  a  number  greater  than 
15,  or  you  misspelled  the  command  name  USER.  Check  your  work 
and  try  again. 

filename*!  or  NO  FILE 

These  messages  may  appear  if  you  change  user  areas,  and  attempt 
to  access  programs  or  data  not  in  the  current  user  area. 

d: 

Change  Default  Disk  Drive 

On  a  system  with  two  or  more  drives,  change  the  currently  active 
(default)  drive  by  typing  the  letter  representing  the  drive  being  logged  into, 
followed  by  a  colon. 

B: 
C: 
L: 

To  revert  to  drive  A,  type 

A: 

When  you  change  the  default  drive,  CP/M  changes  its  prompt  letter. 
Following  B:,  CP/M  returns  with  a  prompt  of  B>.  CP/M-PLUS  would 
return  either  with  B>  if  the  user  area  was  0,  or  nB>  if  the  user  area  was  other 
than  0. 

When  selecting  a  file  on  the  default  drive,  you  do  not  have  to  type  the 
drive  letter  with  the  file  name;  but  in  any  reference  to  files  on  drives  other  than 
the  default  you  must  specify  the  desired  drive. 

This  error  message  will  appear  if  you  attempt  to  change  to  a  drive  that 
does  not  exist  or  that  CP/M  cannot  find  (perhaps  because  the  power  is  OFF  or 
the  drive  door  is  left  open). 


BDOS  ERR  ON  d:  SELECT 
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Control-Character  (Line-Editing) 
Commands  Detailed 

Line-editing  commands,  which  consist  of  control  characters  typed  on  the 
command  line,  let  you  correct  typing  errors  while  entering  command  lines 
and  give  you  some  control  over  the  console  display  (output).  The  line-editing 
commands  are  grouped  by  function,  as  shown  in  Table  10-2. 

The  CTRL-P  and  CTRL-S  commands  are  useful  almost  any  time  CP/M  is 
in  control  of  your  system,  as  is  —  usually — the  CTRL-H  command  (some 
programs,  most  notably  word  processing  and  spreadsheet  programs,  usurp 
this  duty  from  CP/M).  The  other  line-editing  commands  must  normally  be 
typed  within  a  CP/M  command  line:  that  is,  after  the  CP/M  prompt  appears 
and  before  you  press  RETURN  to  process  the  command. 

The  line-editing  commands  can  often  be  used  when  typing  input 
requested  by  transient  programs.  Their  usefulness  in  this  case  will  depend  on 
the  program. 


TABLE  10-2.  Line-Editing  Codes  Grouped  by  Function 


Function 

Codes  Sent 
to  Computer 

Terminate  command  line 

carriage  return      (  <cr>  ) 

line  feed              (  <lf>  ) 

CTRL-J 

CTRL-M 

Cancel  command  line 

CTRL-U 

CTRL-X 

Recall  command  line 

CTRL-W 

Cancel  portion 

delete                 (  <del>  ) 

of  command  line 

CTRL-H 

CTRL-K 

Display  control 

CTRL-E 

CTRL-R 

CTRL-S 

CTRL-Q 

Printer  control 

CTRL-P 

Cursor  control 

CTRL- A 

CTRL-B 

CTRL-F 

CTRL-G 

Restart  CP/M 

CTRL-C 
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CTRL-A 

Advance  Cursor  One  Space  to  Right 

Pressing  CTRL-A  while  typing  on  the  command  line  allows  you  to  move 
the  cursor  one  space  to  the  right  without  affecting  anything  else  that  has 
already  been  typed. 

CTRL-A,  in  conjunction  with  CTRL-B,  CTRL-F,  CTRL-G,  CTRL-K,  and 
CTRL-W,  allows  you  to  edit  command  lines  without  having  to  retype  them. 

CTRL-B 

Cursor  to  Beginning  (or  End) 
Of  Command  Line 

The  CTRL-B  character  moves  the  cursor  to  the  beginning  of  the  com- 
mand line  without  changing  anything  already  typed.  If  the  cursor  is  already  at 
the  beginning  of  the  command  line,  CTRL-B  moves  the  cursor  to  the  end  of  the 
command  line. 

CTRL-B,  in  conjunction  with  CTRL-A,  CTRL-F,  CTRL-G,  CTRL-K,  and 
CTRL-W,  allows  you  to  edit  command  lines  without  having  to  retype  them. 

CTRL-C 

Restart  CP/M 

A  warm  start  restores  CP/ NTs  internal  information  to  a  predefined  state 
without  destroying  programs  or  data  stored  in  memory.  A  warm  start  is  also 
called  a  warm  boot.  In  CP/M,  the  warm  start  command  has  two  primary 
uses. 

•  To  log  in  a  disk  when  you  insert  a  different  disk  into  one  or  more 
drives 

•  To  interrupt  the  current  transient  program  and  return  to  the  CP/M 
command  level 

You  can  create  problems  if  you  do  not  "close  a  file"  (tell  CP/M  that  you 
are  through  with  a  file)  at  the  proper  time.  You  can  avoid  such  problems  by 
always  allowing  a  program  to  end  normally.  If  there  is  an  option  in  the 
program  to  QUIT,  use  it  rather  than  pressing  RESET  or  CTRL-C. 

If  you  change  disks  without  telling  CP/M,  strange  things  may  happen. 
Always  press  CTRL-C  after  you  insert  a  different  disk  into  a  disk  drive  when 
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you  are  using  CP/M,  unless  the  disk  is  specifically  requested  by  the  program. 
In  this  latter  instance,  you  have  to  assume  that  the  programmer  knew  that  you 
were  changing  disks  and  that  instructions  were  included  to  inform  CP/M  of 
the  requested  change. 

CP/M  can  usually  detect  a  switched  disk  and  will  display  the  error 
message 

BDOS  ERR  ON  d:  R/O 

where  d:  is  the  drive  identifier.  When  it  does,  it  will  set  the  read-only 
attribute  for  that  disk.  If  any  program  subsequently  tries  to  write 
information  onto  that  disk,  this  error  message  appears.  The  only  way 
to  recover  from  this  error  and  not  destroy  information  on  your  disk 
is  to  press  CTRL-C. 

For  the  experienced:  You  will  notice  that  the  error  message  you 
receive  when  CP/M  detects  a  switch  in  disks  mentions  the  disk  is 
read-only.  This  error  message  implies  that  you  can  switch  disks  at 
any  time,  as  long  as  you  only  read  from  the  disk.  If  you  use  your 
system  like  most  users,  it  is  rare  for  a  disk  to  be  read  from,  but  not 
written  to;  thus,  this  is  a  potentially  dangerous  suggestion. 

CTRL-E 

Continue  Typing  on  Next  Line 

To  continue  typing  a  long  command  on  the  next  line  of  the  console 
display,  press  CTRL-E.  This  moves  the  cursor  to  the  beginning  of  the  next  line. 
When  you  ultimately  press  RETURN,  the  entire  command  line  is  used,  even 
though  it  may  appear  as  several  lines  on  the  display.  The  CTRL-E  character 
itself  is  not  considered  part  of  the  resulting  command  line. 

CTRI^F 

Insert  a  Space  at  Cursor  Position 

The  CTRL-F  command  inserts  a  single  space  at  the  current  cursor  posi- 
tion on  the  command  line,  effectively  moving  all  characters  from  the  cursor 
position  to  the  end  of  the  line  one  space  to  the  right. 

CTRL-F,  in  conjunction  with  CTRL-A,  CTRL-B,  CTRL-G,  CTRL-K,  and 
CTRL-w,  allows  you  to  edit  command  lines  without  having  to  retype  them. 
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CTRL-G 

Move  Cursor  One  Space  to  Left 

Pressing  CTRL-G  while  typing  on  the  command  line  allows  you  to  move 
the  cursor  one  space  to  the  left,  without  affecting  anything  else  that  has 
already  been  typed. 

CTRL-G,  in  conjunction  with  CTRL-A,  CTRL-B,  CTRL-F,  CTRL-K,  and 
CTRL-W,  allows  you  to  edit  command  lines  without  having  to  retype  them. 

CTRL-H 

Delete  Last  Character 

CP/M-PLUS  allows  you  to  use  CTRL-H  to  correct  simple  typing  errors 
before  pressing  RETURN. 

CTRL-H  is  similar  to  INS/ DEL;  it  differs  in  that  it  erases  the  unwanted 
character  from  the  screen,  while  INS/ DEL  leaves  the  unwanted  character  on 
the  screen  and  repeats  it. 

CTRL-H  is  intended  for  video  displays  rather  than  printers.  CP/M  will 
respond  correctly  to  CTRL-H  even  if  you  are  using  a  printer;  the  printer  may 
respond  strangely,  however. 

INS/DEL 

Cancel  One  Character  and  Echo  It 

The  INS/  del  key  cancels  the  last  uncancelled  character  in  the  command 
line  and  echoes  (repeats)  it. 

Versions  1.3  and  1.4  usually  lack  the  true  backspacing  delete  that  was 
described  in  the  section  on  CTRL-H.  Instead,  these  versions  almost  always 
perform  the  delete  function  that  echoes,  or  repeats,  each  deleted  character. 
Type  BLA  and  then  press  INS/ DEL;  you  will  see  either 

BLAA  Deleted  characters  are  echoed 

or 

BL  Deleted  characters  are  erased  (rubbed  out). 

Echoed  characters  may  seem  a  little  strange  to  computing  novices.  When 
CP/M  was  first  designed,  the  primary  console  device  on  most  microcomput- 
ers was  a  Teletype  or  similar  printer.  These  printers  cannot  backspace.  In 
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order  to  show  that  a  character  was  erased,  Digital  Research  used  echoing  in 
the  earliest  versions  of  CP/M. 

Today,  most  computers  use  high-speed  video  display  consoles.  Such 
consoles  have  the  ability  to  backspace  and  erase  characters. 

CTRL-J 

CTRL-M 

Line  Feed  and  Carriage  Return 

You  can  substitute  CTRL-J  for  the  RETURN  key.  Pressing  CTRL-M  is 
exactly  the  same  as  pressing  RETURN  when  typing  CP/M  commands. 

CTRL-K 

Delete  to  End  of  Line 

The  CTRL-K  command  erases  all  information  on  the  command  line  from 
the  current  cursor  position  to  the  end  of  the  line. 

CTRL-K,  in  conjunction  with  CTRL-A,  CTRL-B,  CTRL-F,  CTRL-G,  and 
CTRL-W,  allows  you  to  edit  command  lines  without  having  to  retype  them. 

CTRL-P 

Assigning  Output  to  the  Printer 

To  turn  ON  the  printer,  press  CTRL-P.  If  you  have  a  printer,  all  output 
going  to  the  console  display  is  now  also  sent  to  the  printer. 

CTRL-P  works  like  a  push-on,  push-off  switch:  type  it  once  to  turn  the 
printer  ON;  type  it  a  second  time  to  turn  it  OFF. 

Some  programs  disable  the  printer  automatically,  whether  or  not  you 
have  selected  it.  These  programs,  such  as  WordStar,  have  other  commands 
for  sending  information  to  the  printer. 

Likewise,  if  you  purchased  your  programs  as  complete,  prewritten 
(canned)  packages,  they  may  turn  the  printer  ON  and  OFF  as  necessary.  Do 
not  press  CTRL-P  before  executing  such  a  program  unless  directed  by  the 
manual;  let  the  computer  do  this  work  whenever  possible. 

A  problem  that  can  occur  is  that,  immediately  after  you  press  CTRL-P, 
the  system  can  "lock  up"  or  stop  accepting  characters  from  you.  If  this 
happens,  it  usually  means  that  the  printer  is  either  not  connected  properly 
(check  to  see  if  it  is  unplugged)  or  not  turned  ON. 
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CTRL-Q 

Unpause  Display 

Pressing  CTRL-Q  causes  the  resumption  of  normal  screen  display 
("unpauses"  the  screen)  that  has  been  paused  with  the  CTRL-S  command. 

CTRL-S 

Pause  the  Display 

CP/M  can  pause  the  console  display.  Like  a  freeze  frame  in  film, 
everything  stops  until  you  tell  CP/M  to  begin  again.  Pause  the  screen  by 
pressing  CTRL-S.  Another  CTRL-S  resumes  the  output  to  your  display.  Actu- 
ally, typing  any  character  except  CTRL-C  will  resume  the  output  to  display. 
CTRL-S  really  pauses  the  computer  and,  as  a  result,  the  display  pauses. 

Pausing  the  display  is  not  the  best  possible  answer  to  handling  overflow 
on  the  screen,  however.  Generally  you  are  surprised  by  the  overflow  or 
respond  too  slowly  to  pause  the  frame  exactly  where  you  want.  Good  pro- 
grams use  formatted  screen  output  and  never  attempt  to  put  more  informa- 
tion on  the  screen  than  it  can  handle.  Good  programs  also  include  an 
automatic  stop  at  the  end  of  each  screen  of  information  and  wait  for  you  to 
press  RETURN  (or  some  other  key)  before  resuming  output.  In  short,  if  you 
find  yourself  using  the  CTRL-S  key  while  executing  a  program,  you  might 
consider  other  programs  with  better  interfacing,  or  you  could  ask  your 
vendor  to  modify  your  program. 

CTRL-U 

CTRL-X 

Cancel  Current  Command 

If  you  start  typing  gibberish,  don't  worry  —  it  happens  to  all  of  us. 
Perhaps  you  typed 

A>DIRG  A: THOMKJLSK- SAB=SLIUF 

which  makes  no  sense  whatsoever.  Instead  of  using  the  INS/ DEL  key  to  get 
back  to  the  first  mistake,  you  may  find  it  easier  to  start  over  by  pressing 
CTRL-U.  CP/M  will  ignore  what  you  have  already  typed  and  move  to  the 
beginning  of  the  next  line.  CP/M  places  a  number  sign  (#)  at  the  end  of  the 
cancelled  line. 
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CTRL-W 

Recall  and  Display  Previously 
Entered  Command  Line 

The  CTRL-W  command,  when  entered  as  the  first  character  on  a  line,  will 
recall  the  most  recent  command  line  entered  into  the  system,  either  at  the 
system  prompt  or  from  within  an  executing  program. 

CTRL-W,  in  conjunction  with  CTRL-A,  CTRL-B,  CTRL-F,  CTRL-G,  and 
CTRL-K,  allows  you  to  edit  command  lines  without  having  to  retype  them. 


CP/M  TRANSIENT  COMMANDS 

In  the  last  section,  CP/M's  built-in  commands  were  introduced.  CP/M  also 
allows  you  to  expand  the  basic  set  of  commands  with  additional  programs 
that  act  like  commands. 

A  Program  in  the  Context  of  CP/M 

Recall  from  the  last  section  that  built-in  commands  are  those  words  that 
CP/M  can  interpret  using  only  the  instructions  already  present  in  memory, 
while  transient  commands  (usually  referred  to  as  programs)  are  invoked  by 
typing  a  command-like  phrase  that  tells  CP/M  to  get  further  instructions 
from  the  disk. 

How  does  CP/M  know  what  other  instructions  are  available  on  the  disk? 
If  you  type  something  in  response  to  the  CP/M  command  prompt  that  CP/M 
does  not  recognize  as  a  command,  CP/M  searches  the  disk  directory  for  a  file 
with  the  .COM  file  type  matching  the  first  word  you  type.  Suppose  you  type 

A>BUY 

After  realizing  that  BUY  is  not  a  built-in  command,  CP/M  looks  for  a  file 
entitled  BUY.COM  on  the  current  disk  drive.  If  there  is  no  such  file,  CP/M 
issues  the  error  message  BUY?.  If  such  a  file  does  exist,  CP/M  loads  the 
contents  of  that  file  into  memory  and  transfers  control  to  the  first  instruction 
in  it. 

The  value  of  the  transient  command  facility  in  CP/M  is  that  if  the  file 
contains  instructions  for  the  computer  to  do  something,  CP/M  will  respond 
as  if  you  had  typed  a  valid  CP/M  command  (although  it  might  take  a  bit  more 
time  since  the  disk  must  be  accessed  before  the  program  starts  working). 
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What  is  this  program  that  acts  like  a  command?  For  the  time  being, 
assume  the  word  program  in  the  context  of  CP/M  is  defined  as  a  set  of 
instructions  that  is  stored  on  disk  in  a  file  with  the  .COM  type,  and  that  is 
invoked  by  typing  its  filename.  This  program  is  often  called  a  transient 
program  or  transient  command. 

After  a  program  is  loaded  from  the  disk  into  the  memory  of  your 
computer,  the  computer  temporarily  ignores  CP/M  and  obeys  the  instruc- 
tions in  the  program.  A  hypothetical  DISPLAY.COM  program  might 
instruct  the  computer  to 

1 .  Ask  you  for  the  name  of  the  file  you  wish  to  display 

2.  Go  to  the  disk  and  find  the  file  you  requested 

3.  Read  a  character  from  the  file 

4.  Display  the  character  on  the  console  display 

5.  If  there  are  more  characters  left,  go  back  to  step  3 

6.  Return  to  CP/M. 

Invoking  a  Program 

The  command  line  is  what  you  type  after  the  CP/M  prompt  A>,  up  to  but  not 
including  the  carriage  return.  Quite  different  from  the  eight-character  limita- 
tion on  filenames,  command  line  in  CP/M  can  be  up  to  128  bytes  long  —  you 
can  type  up  to  128  characters  for  a  single  command! 

Just  as  you  can  add  extra  refinements  to  some  built-in  commands  by 
typing  further  information,  you  also  can  invoke  programs  with  additional 
information.  When  you  type  DIR  B:*.BAS,  for  instance,  the  built-in  com- 
mand is  DIR,  but  B:*.BAS  refines  the  command.  For  lack  of  a  better  name  or 
even  an  established  standard,  this  additional  information  will  be  called 
parameters.  There  can  be  more  than  one  parameter  in  a  command  line. 

To  recap  briefly,  a  generalization  of  the  command  line  format  looks  like 

this: 

A>  COMMAND  PARAMETERS 

^  CP/  M  prompt      ^  Additional  refinements 

-Command  to  be  executed 


Likewise,  the  general  way  that  a  transient  command,  or  program,  is 
invoked  is 


A>  FILENAME  PARAMETERS 

t  1  t  


-CP/  M  prompt 
-File  to  be  loaded  and  executed 


-Additional  refinements 
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Now  what  are  the  parameters  you  give  the  program?  There  is  no  simple 
answer;  some  programs  use  no  additional  parameters,  some  have  optional 
parameters,  while  some  require  parameters.  You  may  give  no  parameters  to 
the  program  or  as  many  as  the  command  line  can  hold. 

You  now  have  all  of  the  information  you  need  to  proceed.  While  you  have 
seen  the  entire  list  of  built-in  commands  that  CP/M  recognizes,  you  have 
barely  glimpsed  the  number  of  programs  that  may  be  loaded  and  executed  as 
transient  commands.  The  remainder  of  this  chapter  deals  with  some  impor- 
tant transient  commands  that  Digital  Research  provides  with  CP/M,  as  well 
as  some  Commodore-provided  programs  that  may  be  important  to  you. 

Housekeeping  Utilities 

For  computer  users,  housekeeping  is  the  job  of  maintaining  the  environment 
in  which  a  computer  program  and  its  data  operate.  A  well-maintained 
environment  ensures  proper  storage  and  retrieval  of  information;  you  place 
your  information  so  that  you  can  find  it  easily  later. 

Consider  a  file  cabinet  in  which  you  arrange  files  for  easy  access.  What 
happens  when  the  file  cabinet  becomes  full?  If  you  are  in  a  hurry,  do  you  still 
maintain  everything  in  the  proper  order?  How  do  you  retrieve  an  item  that 
temporarily  resides  not  in  the  cabinet  but  on  a  desk?  The  answers  to  these 
questions  suggest  the  routine  housekeeping  chores  necessary  to  maintain  the 
integrity  of  the  information  kept  in  the  file  cabinet. 

Now  consider  the  disk  used  to  store  information  (and  instructions)  as  an 
electronic  file  cabinet.  Just  like  a  regular  file  cabinet,  this  electronic  one  can 
become  full,  get  out  of  order,  or  lack  information  that  is  stored  elsewhere. 

Clearly,  you  need  a  few  housekeeping  routines  to  maintain  that  elec- 
tronic cabinet,  the  disks.  These  routines  must  perform  the  following  house- 
keeping tasks: 

•  Ascertain  the  current  status  of  a  disk 

•  Rearrange  the  information  on  the  disk 

•  Expand  the  filing  capabilities. 

"Aha,"  you  say,  "I  already  have  some  commands  that  perform  these 
tasks."  True,  you  could  categorize  the  built-in  commands  presented  by  func- 
tion, as  shown  in  Table  10-3.  However,  these  commands  are  not  sufficient  for 
usefully  altering  a  disk  or  for  doing  major  reordering.  Fortunately,  Digital 
Research  provides  a  number  of  housekeeping  utilities  to  help  you  keep  your 
disk  in  order.  These  transient  programs  are  shown  in  Table  KM. 

Like  the  built-in  commands,  the  transient  housekeeping  commands  can 
be  categorized  by  function,  as  shown  in  Table  10-5. 
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TABLE  10-3.  Built-in  Commands  by  Use 


Command 

diaius 

Rearranging 

Expansion 

DIR 

X 

ERA 

X 

REN 

X 

SAVE 

X 

TYPE 

X 

USER 

X 

DUMP 

Displaying  the  Contents  of  a  File 

DUMP  presents  the  contents  of  a  file  in  both  hexadecimal  and  ASCII 
form. 

DUMP  operates  like  the  TYPE  command  discussed  earlier.  But  instead 
of  presenting  the  ASCII  representations  of  the  file,  DUMP  presents  the 


TABLE  10-4.  Transient  Programs  Supplied  With  CP/M  and  MP/M 


CP/M-80 

CP/M-PLUS 

MP/M 

STAT.COM 

SHOW.COM 

STAT.  PR  L 

PlP.COM 

PIRCOM 

PIP.PRL 

ED.COM 

ED.COM 

ED. PRE 

DUMP.COM 

DUMP.COM 

DUMP.PRL 

SYSGEN.COM 

COPYSYS.COM 

MOVCPM.COM 

SUBMIT.COM 

SUBMlT.COM 

SUBMITPRL 

XSUB.COM 

GET.COM 

DEVlCE.COM 

SET.COM 

DATE.COM 

TOD.PRL 

HELP.COM 

INITDIR.COM 

PATCH.COM 

PUT.COM 

SETDEF.COM 

CONSOLE.PRL 

DSKRESET.PRL 

SPOOL.PRL 

STOPSPLR.PRL 

SCHED.PRL 

ABORT.PRL 
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TAB1£  10-5.  Transient  Programs  by  Use 


Command 

Status 

Rearranging 

Expansion 

STAT 

X 

X 

X 

DEVICE 

X 

X 

X 

SET 

X 

X 

SHOW 

X 

PIP 

X 

X 

ED 

X 

X 

X 

DUMP 

X 

COPYSYS 

X 

X 

SYSGEN 

X 

X 

MOVCPM 

X 

X 

DATE 

X 

X 

GET 

X 

HELP 

X 

JNJTD1R 

X 

X 

PATCH 

X 

PUT 

X 

X 

SETDEF 

X 

X 

SUBMIT 

X 

X 

XSUB 

X 

X 

contents  of  the  file  in  hexadecimal  form.  Assembly  language  programmers 
use  the  DUMP  command  to  check  the  contents  of  a  program  file,  a  binary 
data  file,  or  any  non-ASCII  file. 

The  allowable  forms  for  this  command  are 

DUMP  d:fllename.  typ 

Displays  the  hex  representation  of  each  byte  stored  in  the  file  with 
the  name filename.typ  on  drive  d:.  CTRL-S  pauses  DUMP;  press  any 
key  to  interrupt  DUMP  and  return  to  A>. 

DUMP  d:*.* 

Displays  the  hex  representation  of  the  first  file  that  matches  the  *.* 
(or  other  ambiguous)  filename.  CTRL-S  pauses  DUMP;  press  any 
key  to  interrupt  DUMP  and  return  to  A>. 

DUMP  is  used  as  shown: 

A > DUMP  B: PROGRAM- COM 
DUMP  —  Version  3-0 

OOOO:  3A  07  00  FE  C8  DA  AC  03  21  00  00  39 
0010:  00  C8  3E  11  D3  FD  21  27  07  7D  D3  FD 
0020:  3B  02  1 1  13  04  CD  28  02  CD  3B  02  11 
A> 


22  25  07  31 
7C  D3  FD  CD 
55  04  CD  28 
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The  four-digit  number  that  appears  at  the  start  of  each  line  is  the  relative 
address  of  the  first  byte  on  that  line.  The  pairs  of  hexadecimal  digits  represent 
each  byte  of  the  stored  file,  one  pair  for  each  byte  in  the  file. 

A  period  in  the  ASCII  display  section  indicates  a  nondisplayable  charac- 
ter, such  as  the  control  characters  (ASCII  20-7F  hex  are  displayable 
characters). 

ED 

Context  Editor 

ED  is  a  program  with  a  number  of  built-in  commands  used  to  edit  text 
files.  You  may  have  wondered  how  to  put  something  new  onto  a  disk.  The 
answer  is  that  you  use  an  editor.  The  editor  CP/  M  includes  is  ED,  and  you  will 
find  it  saved  in  the  file  ED.COM. 

The  editor  is  a  program  that  takes  characters  from  the  keyboard  and 
puts  them  in  a  disk  file.  Since  you  may  make  entry  errors  or  wish  to  make 
changes,  the  editor  also  includes  a  number  of  built-in  commands  that  display, 
modify,  delete,  and  add  to  the  information  you  have  typed. 

The  CP/M  editor  (called  context  editor  by  Digital  Research)  is  both 
character-  and  line-oriented;  commands  operate  on  text  either  a  character  at  a 
time  or  a  line  at  a  time.  (A  line  is  a  block  of  characters  ending  in  a  carriage 
return.) 

In  CP/M-PLUS,  three  possible  input  forms  are  allowed: 

ED  x:filename.typ 

This  form  allows  you  to  specify  a  disk  drive  for  input  to  come  from 
and  output  to  go  to. 

ED  x:filename.typ  y: 

This  form  is  the  same  as  the  first  form,  except  the  temporary  output 
file  is  generated  on  drive  y.  This  form  is  used  when  there  is  not 
enough  room  on  the  original  disk  to  hold  both  the  original  file  and 
the  edited  file. 

ED  x:i-filename.typ  z:o-filename.typ 

This  form  is  the  same  as  the  first  form,  except  that  all  input  is  from 
i-filename.typ  (on  drive  x,  if  specified)  and  all  output  goes  to 
o- filename  Ay p  (on  drive  z,  if  specified).  This  form  is  used  when  the 
original  file  is  read-only  or  resides  on  a  write-protected  disk. 

For  example,  suppose  the  file  MYFILE.TEX  requires  editing.  To  edit 
this  file,  type 

A>ED  MYFILE.TEX 
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ED  creates  the  temporary  file  MYFILE.$$$  on  the  disk.  This  file  contains  no 
information;  it  contains  only  the  structure  of  the  file  to  be  written. 

In  order  to  make  changes  to  the  original  file  MYFILE.TEX,  you  must  be 
able  to  see  the  text  and  manipulate  it.  ED's  commands  permit  you  to  move 
text  from  the  original  file  into  memory,  view  the  text  that  you  have  moved  into 
memory,  make  the  required  changes,  and  move  the  text  from  memory  back  to 
the  file.  You  can  only  edit  a  file  while  it  is  in  memory.  The  area  of  memory  ED 
sets  aside  to  hold  text  is  called  the  edit  buffer. 

As  you  progress  in  your  editing,  you  will  move  more  text  from  the 
original  file  into  the  edit  buffer  for  editing.  The  edit  buffer  holds  a  limited 
amount  of  text;  as  it  becomes  full,  you  must  move  the  edited  text  to  the 
temporary  file  MYFILE.$$$.  The  overall  ED  operation  is  shown  in  Figure 
10-1. 

Since  movement  throughout  the  entire  text  may  require  shifting  bodies 
of  text  in  and  out  of  the  edit  buffer  in  the  direction  shown  by  the  arrows  in 
Figure  10-1,  you  basically  move  forward  through  the  text  (the  H  command 
allows  you  to  restart  from  the  head  of  the  file).  This  will  be  explained  in  more 
detail  later.  Examine  the  ED  commands  on  the  following  pages  to  learn  how 
to  perform  the  tasks  described. 

ED  Commands 

To  use  ED  commands,  invoke  ED  and  follow  ED's  prompt  (*  or  :*)  with  the 
proper  command,  as  follows: 

A>ED  -f  i  lename.  typ 
*edcommand 

Several  abbreviation  conventions  will  be  used  in  this  section.  Whenever 
a  plus  or  minus  sign  can  be  typed,  you  will  see  the  symbol  +,  which  stands  for 
plus  (+)  or  minus  (— );  if  you  type  neither  +  nor — ,  ED  assumes  you  mean  +  . 
Whenever  a  number  can  be  typed  to  give  the  command  further  information, 
you  will  see  the  symbol  n.  An  "n"  can  be  any  decimal  integer  number  in  the 
range  0  through  65535,  inclusive.  Do  not  use  a  comma  between  digits.  If  you 
omit  the  number,  ED  assumes  a  value  of  1.  Typing  a  zero  (0)  has  a  special 
meaning  for  some  commands.  If  you  type  a  number  sign  (#),  ED  substitutes 
65535. 

For  the  purposes  of  ED,  a  line  of  text  is  a  sequence  of  zero  or  more 
characters  followed  by  a  carriage  return  character  and  a  line  feed  character. 
This  character  pair  will  be  represented  by  the  symbol  [CRLF].  When  you  type 
a  line  of  text  for  ED  and  then  press  RETURN,  ED  adds  the  line  feed  character 
so  that  the  line  ends  with  [CRLF]. 
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FIGURE  10-1.  Overall  ED  operation 


ED  commands  can  be  divided  into  four  functions: 

Transferring  Text.  These  commands  transfer  by  line  or  by  blocks  of  text 

•  from  the  original  file  into  the  edit  buffer 

•  from  the  edit  buffer  into  the  temporary  file 

•  from  the  original  file  to  the  temporary  file 
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•  from  the  edit  buffer  into  another  file  (not  the  original  or  the  temporary 
file  but  a  distinct  file  on  a  disk) 

•  from  another  file  (not  original  or  temporary  but  a  distinct  file  on  the 
disk)  into  the  edit  buffer 

Working  in  the  Edit  Buffer.  An  imaginary  character  pointer  (CP)  locates 
the  text  in  the  edit  buffer.  These  editing  commands 

•  insert  text  into  the  edit  buffer 

•  manipulate  text  within  the  edit  buffer  in  relation  to  the  CP 

•  direct  movement  of  the  CP 

Searching  and  Changing  Text.  These  commands  work  within  the  edit 
buffer  to 

•  search  for  a  particular  set  of  characters 

•  substitute  a  set  of  characters 

•  switch  placement  between  sets  of  characters 

•  move  text  from  the  original  file  through  the  edit  buffer  to  the  tempo- 
rary file  automatically  while  searching 

Combining  Commands.  A  string  of  ED  commands  can  be  entered  in  one 
command  line  ending  with  a  RETURN  to  permit  a  variety  of  editing  functions 
and  to  repeat  a  command  string  a  specified  number  of  times. 

Commands  for  Transferring 
Text 

Here  are  descriptions  of  the  commands  for  transferring  text. 
nA 

Appends  (copies)  a  number  of  lines  from  the  original  file  to  the  edit 
buffer.  To  move  a  single  line,  enter  only  A;  1  is  the  default  number  of  lines  to 
move.  To  move  the  maximum  number  of  lines  into  the  edit  buffer,  include  the 
number  (nA).  The  nA  command  moves  lines  until  the  original  file  is 
exhausted  or  the  edit  buffer  is  full.  To  move  a  portion  of  the  text  into  the  edit 
buffer,  enter  OA;  this  moves  text  from  the  original  file  until  the  edit  buffer  is  at 
least  half  full.  Once  appended,  lines  in  the  original  file  are  ignored  by 
subsequent  commands  that  read  from  the  original  file. 
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nW 

Write  a  number  of  lines  from  the  edit  buffer  to  the  temporary  file.  To 
write  a  single  line,  enter  only  W;  1  is  the  default  number  of  lines  to  write.  To 
write  the  maximum  number  of  lines  into  the  temporary  file,  include  the 
number  («W).  The  nW  command  moves  lines  until  the  edit  buffer  is 
exhausted.  To  write  a  portion  of  the  text  into  the  temporary  file,  enter  OW; 
this  moves  text  from  the  edit  buffer  until  the  edit  buffer  is  at  least  half  full. 
Lines  written  are  deleted  from  the  edit  buffer  as  they  are  written  to  the 
temporary  file. 

E 

Ends  the  editing  session.  Text  is  transferred,  and  files  are  renamed  as 
follows: 

1.  All  text  remaining  in  the  edit  buffer  moves  to  the  temporary  file,  as 
with  the  W  command. 

2.  All  text  remaining  in  the  original  file  is  then  appended  to  the  tempo- 
rary file. 

3.  The  type  of  the  original  file  becomes  .BAK, 

4.  The  type  of  the  temporary  file  is  changed  to  the  type  of  the  original 
file. 

5.  The  block  move  file  X$$$$$$$.LIB,  if  present,  is  erased.  (For  more 
detail  on  the  file  X$$$$$$$.LIB,  see  the  section  on  nX.) 

6.  The  CP/M  prompt  returns. 

Use  the  E  command  as  the  normal  ending  of  an  editing  session.  To  work 
properly,  E  must  be  the  only  command  on  a  line. 

H 

Moves  to  the  beginning  of  the  file  being  edited  (moves  to  Head).  Text  is 
transferred,  and  files  are  renamed  as  follows: 

1 .  All  text  remaining  in  the  edit  buffer  moves  to  the  temporary  file,  as 
with  the  W  command. 

2.  All  text  remaining  in  the  original  file  is  moved  to  the  temporary  file. 

3.  The  type  of  the  original  file  becomes  .BAK. 

4.  The  type  of  the  temporary  file  is  changed  to  the  type  of  the  original 
file. 


USING  CP/M  379 


5.  A  new,  empty  temporary  file  is  created. 

6.  You  are  now  ready  to  edit  the  new  original  file. 

H  must  be  the  only  command  on  the  line.  The  H  command  has  two 
uses:  First,  since  the  A,  N,  and  W  commands  can  move  only  forward,  not 
backward,  through  the  original  and  temporary  files,  you  use  the  H  command 
to  save  the  editing  done  so  far  and  return  to  the  beginning  of  the  file  for  more 
editing.  Second,  use  the  H  command  every  few  minutes  during  editing  of 
critical  files  to  save  your  results  on  the  disk.  Text  left  in  the  edit  buffer  is 
generally  lost  if  an  operator  error  or  equipment  malfunction  occurs,  but  text 
saved  in  the  temporary  file  is  easily  recovered. 

Frequent  use  of  H  is  especially  important  when  inserting  a  lot  of  text  or 
making  numerous  changes.  However,  remember  that  the  H  command  makes 
a  new  backup  file;  this  means  that  after  using  the  H  command  twice,  the 
original  file  as  it  was  before  beginning  the  editing  session  is  lost.  For  this 
reason,  if  you  anticipate  using  the  H  command  often,  use  PIP  (see  the  PIP 
section  later  in  this  chapter)  to  make  your  own  second  copy  of  the  original  file. 
(Do  not  call  it  type  .BAK;  use  .OLD  or  place  it  on  a  different  drive  to  be  safe). 

O 

Erases  the  edited  file.  Text  is  transferred  as  follows: 

1.  The  contents  of  the  edit  buffer  and  the  temporary  file  are  deleted. 

2.  You  are  returned  to  the  beginning  of  the  original  file. 

ED  asks  0-(Y/N)?  before  it  proceeds,  since  all  changes  made  to  the  text 
are  erased  when  the  O  command  executes.  Press  Y  to  return  to  the  original  file 
or  N  to  continue  editing. 

O  must  be  the  only  command  on  the  line. 

Q 

Quits  editing;  does  not  institute  any  changes.  ED  asks  Q-(Y/  N)?  before  it 
proceeds,  since  all  changes  made  to  the  text  are  erased  when  the  Q  command 
executes.  Press  Y  to  quit  editing  or  N  to  continue  the  editing  session. 

Q  must  be  the  only  command  on  the  line. 

RAZ 

Reads  the  file  created  by  the  X  command  into  the  edit  buffer.  R  inserts 
the  entire  contents  of  the  transfer  file  X$$$$$$$.LIB  into  the  edit  buffer 
immediately  after  the  character  pointer  (CP).  The  transfer  file  is  not  affected; 
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you  can  read  it  as  many  times  as  you  want  during  an  editing  session.  The 
transfer  file  is  automatically  erased  when  you  leave  ED  with  the  E,  Q,  or 
CTRL-C  commands. 

Rfilename  Z 

Reads  the  library  file  filename.LIB  into  the  edit  buffer.  This  command 
inserts  the  entire  contents  of  the  specified  file  into  the  edit  buffer  immediately 
after  the  character  pointer  (CP).  The  library  file  is  not  affected. 

nX 

Writes  (Xfers,  or  transfers)  lines  from  the  edit  buffer  to  a  temporary  file 
named  X$$$$$$$.LIB.  You  may  later  transfer  these  lines  back  to  the  edit 
buffer  by  using  the  R  command.  With  the  X,RAZ/RAZ  command  combina- 
tion you  can  move  blocks  of  information.  The  file  X$$$$$$$.LIB  is  erased 
when  editing  is  completed  with  an  E,  Q,  or  CTRL-C  command.  The  X 
command  copies  the  n  lines  that  follow  the  character  pointer  in  the  edit  buffer 
into  the  transfer  file.  The  lines  are  not  deleted  from  the  edit  buffer,  and  they 
are  added  to  any  previous  contents  of  the  transfer  file. 

In  CP/M-PLUS,  you  may  also  use  OXAZ  to  erase  the  library  file 
X$$$$$$$.LIB,  or  OXfilename.typAZ  to  erase  any  specified  file. 

Commands  for  Working 
In  the  Edit  Buffer 

Here  are  descriptions  of  the  commands  that  allow  you  to  work  in  the  edit 
buffer. 

+B 

Moves  the  character  pointer  to  the  beginning  (use  a  +  or  nothing  before 
the  B)  or  the  end  (use  a  —  before  the  B)  of  the  edit  buffer.  Notice  that  the 
direction  implied  by  the  sign  in  front  of  the  B  command  is  the  opposite  of  that 
for  all  other  commands. 

+nC 

Moves  the  character  pointer  by  plus  or  minus  n  characters.  The  carriage 
return/ line  feed  combination  that  terminates  a  line  in  ED  is  counted  a  two 
separate  characters.  Type  +  5C  to  move  the  character  pointer  five  characters 
toward  the  end  of  the  edit  buffer. 

Deletes  n  characters  immediately  before  (—)  or  after  (+)  the  character 
pointer.  For  example,  imagine  that  you  have  the  line  NOW  IS  THE  TIME 
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FOR  ACTION  with  the  character  pointer  pointing  at  the  T  in  TIME.  If  you 
type  the  command  -3<cr>,  the  result  would  be  NOW  IS  THIME  FOR 
ACTION,  with  the  character  pointer  still  pointing  to  the  I,  now  in  THIME. 

I 

Enters  the  insert  mode.  ED  accepts  all  characters  you  type  and  inserts 
them  into  the  edit  buffer  after  the  character  pointer.  With  certain  exceptions, 
every  character  you  type  goes  into  the  buffer  until  you  press  CTRL-Z.  CTRL-Z 
terminates  the  insert  mode  and  returns  the  ED  prompt.  If  you  enter  an 
uppercase  I,  all  inserted  text  will  automatically  be  translated  to  uppercase- 
only  characters. 

Here  are  some  characters  that  perform  differently  in  the  Insert  mode 
than  you  may  expect. 


Characters 

Function 

CTRL-H 

Deletes  the  last  character  typed 

CTRL-L 

Inserts  a  carriage  return/ line  feed 

CTRL-M  or 

RETURN 

Inserts  a  carriage  return/ line  feed 

CTRL-R 

Redisplays  the  current  line 

CTRL-U 

Deletes  the  current  line 

CTRL-X 

Deletes  the  current  line 

INS/DEL 

Deletes  the  last  character  typed  and 

redisplays  it. 

The  current  line  consists  of  the  characters  that  follow  the  last  carriage 
turn  typed  while  in  the  insert  mode. 

Use  the  insert  mode  to  type  in  a  new  file  or  to  add  several  lines  to  an 
existing  file.  Remember  to  exit  the  insert  mode  and  use  the  save  command  H 
often. 

I  string  Z 

Insert  a  string.  This  command  inserts  the  character  sequence  string  into 
the  edit  buffer  following  the  character  pointer.  Use  this  command  to  insert 
short  strings. 

Istring<cr> 

Insert  a  line.  This  command  inserts  the  character  sequence  "string"  into 
the  edit  buffer  following  the  character  pointer.  A  carriage  return/ line  feed 
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combination,  which  is  symbolized  by  <cr>,  is  inserted  after  the  string.  The 
carriage  return/ line  feed  is  the  difference  between  this  command  and  the 
previous  one.  Use  this  command  to  insert  a  single  line. 

+nK 

Kills  (deletes)  those  lines  from  the  edit  buffer  that  you  do  not  wish  to 
appear  in  the  final  edited  version.  Lines  referenced  by  the  nK  command  are 
not  transferred  to  the  temporary  file  but  remain  in  the  original  file,  which 
later  becomes  the  backup  file.  You  may  remove  any  number  of  lines  from  the 
edit  buffer  in  either  direction  from  the  character  pointer.  +K  or  K  erases  all 
characters  after  the  character  pointer  up  to  and  including  the  current  line's 
carriage  return/ line  feed.  — K  erases  all  characters  in  the  line  before  the 
character  pointer,  back  to  the  first  carriage  return/  line  feed  encountered,  but 
not  includng  it.  If  you  still  have  some  characters  remaining  in  a  line  that  you 
thought  you  had  deleted  using  the  K  command,  check  to  see  if  the  character 
pointer  was  at  the  start  of  the  line  when  you  issued  the  command. 

+nL 

Moves  the  character  pointer  forward  or  backward  n  lines  in  the  buffer. 
First,  the  character  pointer  moves  to  the  beginning  of  the  current  or  next  line 
(that  is,  if  the  character  pointer  is  not  currently  at  the  beginning  of  a  line). 
Subsequent  moves  encompass  full  lines;  the  character  pointer  moves  n  lines 
forward  or  backward.  The  OL  moves  the  character  pointer  to  the  beginning 
of  the  current  line. 

+nP 

Moves  the  character  pointer  one  page  and  displays  the  page  following 
the  character  pointer.  This  command  is  repeated  for  a  total  of  n  pages.  P  is  a 
convenient  method  of  scrolling  through  the  text  in  the  edit  buffer.  A  page  is  a 
fixed  number  of  lines  that  varies  with  the  version  of  CP/  M,  but  usually  is  one 
screenful.  +nP  moves  you  forward  through  the  edit  buffer  and  —  nP  moves 
you  backward.  P  operates  by  first  moving  the  character  pointer  backward  or 
forward  one  page  and  then  displaying  the  page  that  follows  the  character 
pointer.  OP  displays  a  page  without  moving  the  character  pointer. 

+nT 

Displays  lines  of  text  that  are  in  the  edit  buffer.  To  see  the  three  lines 
before  the  character  pointer,  you  would  type  — 3T.  To  see  the  three  lines  after 
the  character  pointer,  type  +3T  or  just  3T.  If  the  character  pointer  is  posi- 
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tioned  at  the  beginning  of  a  line,  type  T  to  see  that  line.  If  the  character 
pointer  is  positioned  within  a  line,  type  OT  to  see  the  part  of  the  line  before  the 
character  pointer,  type  T  to  see  the  part  of  the  line  after  the  character  pointer, 
or  type  OTT  to  see  the  whole  line. 

The  T  command  does  not  move  the  character  pointer;  it  displays  lines  of 
text  in  relation  to  the  character  pointer. 

+U 

Translates  lowercase  letters  to  uppercase.  Type  +U  to  begin  translation 
and  —  U  to  end  translation. 

Ordinarily  ED  does  not  translate  characters.  After  being  given  the 
command  U  or  +U,  however,  ED  translates  characters  that  enter  the  edit 
buffer  either  from  the  keyboard  or  from  the  original  file.  Lowercase  a 
through  z  is  translated  to  uppercase  A  through  Z.  This  translation  continues 
until  ED  receives  the  — U  command  or  the  editing  session  is  concluded.  (Note 
that  you  can  create  a  file  of  all  lowercase  characters  by  using  the  PIP[L] 
parameter,  discussed  later  in  this  chapter.) 

+V 

Displays  line  numbers.  Line  numbers  are  useful  in  identifying  text  and 
moving  the  character  pointer.  (V  stands  for  verify  line  numbers.)  Type  —V  to 
suppress  display  of  line  numbers. 

OV 

Indicates  how  much  of  the  edit  buffer  is  in  use  and  how  much  is  still 
available  for  use.  The  result  is  shown  by  the  editor  in  the  form 

xxxxxj  yyyyy 

The  first  number  ED  reports  (xxxxx)  is  the  amount  of  available  memory  in 
the  edit  buffer;  the  second  (yyyyy)  is  the  maximum  possible  size  of  the  edit 
buffer.  By  subtracting  the  first  from  the  second,  you  can  find  out  how  many 
characters  of  the  file  being  edited  are  currently  in  the  buffer. 

n: 

Moves  to  line  number  n.  When  line  numbers  are  being  displayed  (see  the 
section  on  V),  you  can  use  this  command  to  move  the  character  pointer 
directly  to  the  beginning  of  a  specific  line.  The  n:  command  can  be  used  as  a 
command  prefix,  making  commands  start  at  a  particular  line  number.  For 
example,  75: OP  will  make  ED  move  to  line  75  and  display  a  page  of  text. 
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:n 

Starts  at  the  character  pointer  and  continues  through  line  number  n. 
This  is  not  really  a  command  by  itself,  but  a  prefix  to  a  command.  For 
example,  if  you  type  :75T,  ED  will  type  lines  (T)  beginning  at  the  character 
pointer  (currently  in  line  55)  and  ending  at  line  75. 

Notice  that  you  can  use  this  command  together  with  the  previous  one  to 
perform  an  operation  on  a  specified  range  of  lines.  For  example,  to  delete 
lines  20  through  30,  no  matter  where  the  character  pointer  is,  type  20::30K. 

+n 

Moves  forward  or  backward  and  displays  one  line.  This  is  an  abbreviated 
form  of  the  command  /?LT,  where  the  character  pointer  is  moved  forward  or 
backward  by  n  lines,  whereupon  the  line  then  at  the  character  pointer  is 
displayed. 

The  simplest  form  of  this  command  is  just  a  carriage  return  and  is 
equivalent  to  LT,  which  moves  the  character  pointer  to  the  next  line  and 
displays  it. 

Commands  for  Searching 
And  Changing  Text 

In  this  section  on  searching  and  changing  text,  the  following  rule  applies:  you 
must  use  lowercase  commands  to  search  for  uppercase  and  lowercase 
matches;  an  uppercase  command  means  that  ED  will  only  search  for  upper- 
case matches  to  your  string. 

nFstrlng  Z 

Finds  a  particular  unique  sequence  (string)  of  characters.  If  the  search  is 
successful  (the  string  is  found  the  specified  number  of  times),  the  character 
pointer  is  placed  immediately  following  the  nth  matching  string.  If  you  were 
searching  for  the  first  chorus  of  "Row,  Row,  Row  Your  Boat"  with  the 
command  3fRow,  the  character  pointer  would  come  to  rest  between  "w"  in 
the  last  "Row"  and  the  space  preceding  "Your"  if  its  original  position  was 
before  the  first  letter  of  the  first  "Row."  If  the  search  cannot  satisfy  the 
command  given,  the  character  pointer  does  not  move. 

The  search  begins  at  the  location  of  the  character  pointer,  so  be  sure  it  is 
positioned  well  before  the  string  to  be  found  when  using  the  F  command. 

Remember  that  the  F  command  searches  only  within  the  text  in  the  edit 
buffer;  it  cannot  look  through  text  still  in  the  original  file  or  already  saved  on 
the  disk  —  to  do  so,  see  the  N  command,  described  next. 
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nNstring  Z 

Looks  for  the  string  in  the  edit  buffer  and  on  the  disk.  This  command 
automatically  loads  the  next  portion  of  the  original  file  into  the  edit  buffer 
and  writes  lines  from  the  edit  buffer  to  the  temporary  file  as  necessary.  The  N 
command  (called  autoscan)  acts  on  the  entire  document,  beginning  at  the 
character  pointer,  even  if  portions  of  it  are  still  in  the  original  file,  while  F 
looks  only  in  the  edit  buffer  for  the  string. 

Remember  to  position  the  character  pointer  properly  before  issuing  the 
N  command.  (See  the  F  command  described  earlier.) 

Use  CTRL-L  to  represent  the  carriage  return/ line  feed  pair  if  it  is  part  of 
the  string. 

nSfindstring  Zreplacestring  Z 

Substitutes  information  in  the  edit  buffer.  The  substitute  command  finds 
one  string  and  replaces  it  with  another.  As  shown,  the  command  would  search 
for  findstring  and  replace  it  with  replacestring.  The  searching  begins  at  the 
character  pointer  and  ends  at  the  last  character  in  the  edit  buffer.  The 
substitution  is  performed  a  total  of  n  times. 

As  in  all  substitution  commands,  be  sure  the  strings  you  want  to  replace 
are  unique. 

Use  CTRL-L  to  represent  the  carriage  return/ line  feed  pair  in  the  string. 
nJfindstring  Zinsertstring  Zendstring  Z 

Juxtaposes  two  or  more  unique  strings  one  or  more  times.  This  com- 
mand combines  the  insertion  and  deletion  operations. 

To  use  this  command,  first  find  findstring.  Immediately  following/mc/- 
string,  insert  insertstring,  and  then  delete  all  characters  from  the  end  of 
insertstring  to  the  beginning  of  endstring.  Repeat  a  total  of  n  times.  The 
character  pointer,  assuming  that  the  operation  was  successful,  is  placed  at  the 
end  of  the  final  insertstring. 

For  example,  imagine  that  you  have  in  text  the  line 

WHEN  IN  ROM  DO  AS  THE  ROMANS  DO,  AND  BE  ROMANTIC 

with  the  character  pointer  at  W  in  WHEN.  By  means  of  the  juxtaposition 
command,  JROM  AZDONTAZ  ASAZ  would  result  in 

WHEN  IN  ROM  DON'T  AS  THE  ROMANS  DO,  AND  BE  ROMANTIC 

with  the  character  pointer  at  A  in  AS. 

Be  careful  when  using  multiple  repetitions  of  the  juxtaposition  com- 
mand, as  you  can  often  change  information  you  do  not  mean  to  change. 
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Combining  Commands 

ED  lets  you  group  some  commands  in  one  command  line  to  save  typing  time. 
You  can  cascade  ED  commands  one  after  another  and  follow  the  last  com- 
mand with  the  carriage  return.  For  example,  the  commands  OA,  B,  and  T 
could  be  typed  as  OABT<cr>  all  on  one  line. 

There  are  a  few  simple  rules  to  follow  when  typing  several  commands  on 
one  line. 

•  Some  commands  must  be  typed  alone  in  a  command  line;  these 
commands  are  E,  H,  O,  and  Q.  This  prevents  the  disastrous  conse- 
quences of  certain  typographical  errors. 

•  When  typing  commands  that  use  strings,  use  CTRL-Z  rather  than 
<cr>,  to  end  the  strings.  Commands  that  use  strings  are  F,  I,  J,  N,  and 
S.  Use  <cr>  only  at  the  end  of  the  command  line. 

You  can  create  a  command  sequence  for  frequently  used  commands.  The 
format  is  nMcommandl command2command3 
For  example,  if  you  type 

mromaz-3d:ramott 

the  command  line  says  to  perform  the  following  sequence  of  steps  repeatedly: 

1 .  Find  ROM  (the  character  pointer  is  placed  after  the  M) 

2.  Delete  the  three  previous  characters  (ROM) 

3.  Insert  RAM 

4.  Show  each  line  as  it  is  changed  (OTT). 

This  macro  command  will  change  all  occurences  of  ROM  to  RAM.  If 
used  on  the  previous  example  in  the  J  commands,  the  resulting  line  would 
read:  WHEN  IN  RAM  DO  AS  THE  RAMANS  DO,  AND  BE  RAMAN- 
TIC.  ...  If  n  is  absent  or  is  equal  to  0  or  1,  the  command  sequence  repeats 
until  an  error  condition  develops.  Striking  any  key  aborts  the  macro 
command. 

PIP 

Copying  Information 

PIP,  or  Peripheral  Interchange  Program,  copies  information  from  one 
place  to  another.  The  names  of  the  files  you  wish  to  copy  can  be  ambiguous, 
and  a  number  of  optional  parameters  are  available  for  use.  PIP  can  also  copy 
information  from  and  to  devices. 
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PIP  can  be  invoked  in  one  of  two  ways.  If  you  want  to  perform  only  one 
operation  with  PIP,  invoke  it  as  follows: 

A>PIP  pipcommandline 

If  you  have  several  operations  to  perform,  use  this  second  method  to 
invoke  PIP: 

A>PIP 

*P ipcommand I ine 
*p i pcommand 1 ine 
*-C 

A> 

No  matter  which  method  you  use,  there  is  no  significant  difference  in  the 
manner  in  which  PIP  performs  the  operation  requested  by  pipcommandline. 
One  minor  difference  is  explained  under  the  discussion  of  the  Q  parameter 
later  in  this  section.  Another  difference  is  PIP's  response  to  errors.  If  the 
invocation  method  given  first  is  used,  errors  cause  a  return  to  CP/  M.  If  the 
second  method  is  used,  errors  cause  a  return  to  the  PIP  prompt. 

The  PIP  command  line  (pipcommandline  in  the  examples)  usually  takes 
the  form  of 

destination— sour  ce\parameters\ 

where  destination  is  the  name  of  the  new  file,  source  is  the  name  of  the  old  file, 
and  parameters  are  the  optional  parameters  you  select  for  the  copying 
process. 

If  there  is  already  a  file  with  the  same  name  as  your  destination  file  name, 
the  existing  file  is  erased  after  successful  completion  of  the  copy.  The  previous 
contents  of  the  destination  file  are  lost. 

PIP  command  lines  and  special  parameters  specify  the  transfer  made 
between  two  files  or  two  groups  of  files.  In  every  instance,  the  original  file 
remains  intact;  you  can  duplicate  an  entire  disk  or  only  a  portion  of  a  file 
without  changing  the  original.  You  can  specify  that  certain  characteristics  of 
the  new  file  be  changed  from  the  original  without  changing  the  original. 
When  used  with  files,  PIP  can  do  the  following: 

•  Copy  a  file  from  one  disk  to  another 

•  Create  an  identical  file  with  a  different  name 

•  Copy  several  files  from  one  disk  to  another 

•  Copy  all  files  from  one  disk  to  another 

•  Create  one  file  from  the  concatenation  of  several 

•  Copy  a  portion  of  a  file 
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•  Copy  from  a  system  file 

•  Copy  onto  an  R/O  file 

•  Display  the  contents  of  a  file  while  it  is  being  copied. 

PIP  also  copies  data  from  a  file  to  a  device,  from  a  device  to  a  file,  or 
between  devices;  you  simply  substitute  a  device  name  for  a  filename  in  either 
the  destination  or  source  position,  or  both.  When  you  read  from  or  write  to  a 
device,  as  opposed  to  a  disk  file,  make  sure  you  can  terminate  the  copying 
process.  Some  devices  do  not  emit  an  end-of-file  marker  (AZ)  as  CP/  M  does 
at  the  end  of  every  disk  file. 

When  used  with  devices,  PIP  can  do  the  following: 

•  Send  the  contents  of  a  file  to  a  device,  such  as  a  printer. 

•  Pass  the  data  from  a  device,  like  paper  tape  reader  or  modem,  into  a 
file. 

•  Send  data  from  one  device  to  another. 

•  Print  the  contents  of  a  file,  formatting  it  for  a  special  printer  or  paper 
size. 

•  Display  on  the  console  selected  data  arriving  at  an  input  device. 

•  Convert  uppercase  letters  to  lowercase  or  vice  versa. 

•  Save  in  a  file  all  the  data  arriving  at  an  input  device. 

PIP  has  three  "special"  device  names,  in  addition  to  the  ones  that  will  be 
explained  in  the  section  on  STAT. 

NUL 

A  source  device  that  sends  40  nulls  (do-nothing  characters  —  OO 
hex)  to  the  destination  specified. 

EOF 

A  source  device  that  sends  an  end-of-file  marker  ( A  Z  or  a  1 A  hex)  to 
the  destination. 

PRN 

A  special  form  of  the  LST:  device  that  expands  tabs,  numbers  lines, 
and  paginates  the  copy  (the  same  as  LST:[NPT8]). 

Like  the  devices  discussed  earlier,  these  device  names  are  used  as  sources 
and  destinations  in  the  command  line. 
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Variations  in  Using  PIP 

The  following  is  a  summary  of  the  varieties  of  PIP  commands  that  you  may 
enter. 

PIP 

Loads  PIP  into  memory  for  use;  PIP  commands  entered  individu- 
ally at  PIP  prompt  (*)  with  the  format  destination=source.  A 
RETURN  or  CTRL-C  at  the  PIP  prompt  cancels  PIP  and  returns  you 
to  CP/M. 

PIP  d:new. typ[ Gn]= d:old. typ[options] 

Copies  the  file  old.typ  on  the  drive  specified  to  the  file  new.typ  on 
the  drive  specified  using  the  options  specified  ([options]).  A  single 
option  is  permitted  only  for  the  destination  file — that  of  the  G  (get 
from  user  area)  option  (see  the  section  called  "PIP  Options.") 

PIP  d:new.typ[Gn]=d:oldl.typ[options],d:old2Jyp[options] 

Creates  a  new  file  on  the  drive  specified,  the  new  file  consisting  of 
both  files  oldl.typ  and  oldl.typ.  In  other  words,  a  comma  on  the 
PIP  command  line  indicates  concatenation.  Multiple  files  may 
serve  as  the  source,  but  each  must  be  set  apart  from  the  others  with  a 
comma  on  the  command  line.  Selected  options  apply  only  to  the  file 
immediately  preceding  the  option  list.  A  single  option  is  permitted 
only  for  the  destination  file — that  of  the  G  (get  from  user  area) 
option  (see  the  section  called  "PIP  Options"). 

PIP  dev:=d:filename.typ[options] 

Sends  the  contents  of  a  file  on  the  drive  specified  to  a  device.  You 
may  stop  the  PIP-to-device  process  by  pressing  any  key  while  the 
copying  is  in  progress. 

PIP  d:filename.typ[Gn]=dev:[options] 

Copies  input  from  a  device  to  the  file  name  specified.  Special  Input: 
Both  a  carriage  return  CTRL-M  and  a  line  feed  CTRL-J  must  be 
entered  at  the  end  of  each  line  from  the  source  device.  A  CTRL-Z 
terminates  the  transfer  and  signifies  the  end  of  the  file.  You  may  stop 
the  PIP-to-device  process  by  pressing  any  key  while  the  copying  is 
in  progress.  A  single  option  is  permitted  only  for  the  destination 
file  —  that  of  the  G  (get  from  user  area)  option  (see  the  section  called 
"PIP  Options"). 
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PI  P  destinationdev:=sourcedev:  [  op  Hons  ] 

Copies  data  from  one  device  to  another.  Special  Input:  You  may 
stop  the  PIP-to-device  process  by  pressing  any  key  while  the  copy- 
ing is  in  progress. 

PIP  Options 

This  section  describes  each  of  PIP's  options.  You  will  probably  use  only  one 
or  two  of  these  options  frequently;  you  may  never  use  some  of  them.  You  may 
combine  two  or  more  options  between  the  square  bracket  characters  (such  as 
[BEU])  for  source  files;  destination  files  can  only  use  the  G  option. 

[A]  Transfer  only  modified  files 

The  [A]  option  specifies  that  the  PIP  transfer  should  occur  for  the 
matching  files  only  if  they  have  been  modified  since  the  last  time 
they  were  copied.  (CP/M-PLUS  keeps  an  "archive  bit"  in  the 
directory  entry  for  every  file,  clearing  the  bit  each  time  the  file  is 
copied  and  resetting  the  bit  each  time  the  file  is  modified.) 

[C]  Prompt  for  confirmation 

Use  of  the  [C]  option  causes  PIP  to  prompt  the  user  for  confirma- 
tion before  each  separate  copying  operation  is  performed.  (In  the 
case  of  ambiguous  file  names,  a  confirmation  is  asked  for  each 
matching  file  name  before  copying  it.) 

[Dn]  Delete  all  characters  after  the  nth  column 

[Drc]  tells  PIP  to  delete  any  character  received  that  extends  past  a 
column  number,  which  must  be  specified  immediately  following  the 
D,  as  in  [D20].  This  type  of  transfer  will  work  only  for  line-oriented 
data  (data  that  contains  periodic  carriage  return  characters).  After 
each  carriage  return  is  detected,  PIP  counts  and  processes  charac- 
ters up  to  and  including  the  column  number  specified  and  then 
ignores  all  remaining  characters  sent  until  the  next  carriage  return  is 
received.  (NOTE:  Line  feed  characters  are  interpreted  the  same  as 
carriage  returns  for  this  operation.) 

The  [Dn]  option  is  primarily  used  to  send  wide-lined  output  to 
a  device  that  handles  only  narrow  lines  (like  a  printer  or  CRT 
terminal).  For  file-to-file  transfers,  this  option  is  rarely  used. 

The  value  n  is  a  decimal  integer  in  the  range  1  through  255, 
inclusive.  Input  lines  longer  than  255  characters  are  not  truncated 
properly  by  the  [D«]  option. 
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[E]  Echo  the  copying  to  the  console  as  it  is  performed 

The  characters  sent  to  the  destination  device  are  echoed  to  the 
console  display  during  the  copying  process.  This  is  a  handy  method 
of  reviewing  exactly  what  is  being  copied. 

[F]  Filter  form  feeds  from  the  original  file 

The  [F]  option  "filters"  form  feed  characters  (OC  hex)  from  the  data 
flow;  PIP  ignores  the  ASCII-defined  character  for  form  feeds  and 
copies  without  it.  Form  feeds  are  often  embedded  in  files  for  correct 
pagination  of  the  printed  output.  You  may  wish  to  eliminate  form 
feeds  to  conserve  paper,  to  display  a  file  on  your  console  screen,  or 
to  use  a  printer  that  improperly  interprets  the  form  feed  character. 

The  ASCII  form  feed  character  is  called  FF  and  is  equivalent 
to  hexadecimal  OC  and  CTRL-L. 

The  form  feed  character  is  a  format  character  that  controls  the 
layout  or  positioning  of  information  in  printing  or  display  devices. 
Thus,  a  printer  would  normally  respond  to  this  character  not  by 
printing  it,  but  by  advancing  the  paper  to  the  top  of  the  next  form  or 
page. 

Use  [F]  if  your  printer  does  not  respond  properly  to  form  feed 
characters,  or  if  you  are  sending  a  file  to  a  device  other  than  a 
printer.  (See  also  the  [P#]  parameter.) 

[Gri]  Direct  PIP  to  copy  files  from  other  user  areas 

The  [Gn]  option  allows  PIP  to  copy  files  from  another  user  area  to 
the  current  one.  The  n  is  a  decimal  number  (between  0  and  15, 
inclusive)  that  represents  the  source  user  area  and  should  imme- 
diately follow  the  G  in  the  command  line.  This  option  is  helpful  in 
setting  up  a  user  area  with  files  that  may  be  needed  later. 

[H]  Check  data  transfer  for  proper  Intel  hex  format 

The  [H]  option  specifies  that  the  data  to  be  transferred  is  in  the 
special  Intel  hex  format  rather  than  in  the  normal  ASCII  or  binary 
formats.  The  Intel  format  is  usually  used  with  paper  tape  punch  and 
reader  devices.  Most  users  do  not  utilize  this  option.  When  PIP 
detects  errors  in  the  hex  format,  a  prompt  will  ask  what  corrective 
action  to  take.  (See  also  the  [I]  parameter.) 

[I]  Ignore  any  null  records  in  Intel  hex  format  transfers 

The  [I]  option  also  applies  to  Intel  hex  format  records  (see  [H]).  The 
[I]  option  tells  the  PIP  program  to  ignore  any  data  that  appears  in  a 
null  record  (00:  in  Intel  format).  Again,  this  option  is  rarely  of  use  to 
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end  users,  as  it  applies  primarily  to  paper  tape  reader  and  punch 
devices.  If  the  [I]  option  is  specified,  then  the  [H]  option  is  automat- 
ically set  by  PIP.  Thus  the  PIP  command  line  of 

PUN: =PROGRAM. HEX  111 

is  equivalent  to 

PUN : =PROGRAM -  HEX  CHID 

[L]  Convert  uppercase  letters  to  lowercase 

The  [L]  option  allows  you  to  change  the  letters  A  through  Z  to  their 
lowercase  equivalents  during  the  copying  process.  Be  extremely 
careful  in  using  this  option,  as  it  should  never  be  used  with  files  that 
contain  instructions  to  the  computer.  If  you  do  happen  to  use  it  on  a 
program  file,  you  may  find  that  some  important  instructions  that 
happen  to  look  to  PIP  like  the  letters  A-Z  are  changed  when  they 
should  not  be. 

[N]  Add  line  numbers  to  each  line  during  the  data  transfer 

The  [N]  option  adds  a  line  number  to  each  line  of  data  transferred. 
Each  time  a  carriage  return  (or  line  feed)  is  detected  by  PIP,  the  line 
number  counter  is  incremented.  [N]  is  of  particular  use  when 
transferring  a  file  to  the  printer.  If  a  2  is  appended  to  the  [N]  option 
(such  as  [N2]),  leading  zeros  are  added,  and  the  number  is  printed  in 
a  six-character  field  followed  by  a  three-character  blank  buffer. 
Here  is  the  difference  between  files  transferred  using  these  options: 


Original 

Now  is  the 
time  for  all 
good  persons 
to  come  to 
the  aid  of 
their  party. 


File  Using  [N] 

1 :  Now  is  the 
2:  time  for  all 
3:  good  persons 
4:  to  come  to 
5:  the  aid  of 
6:  their  party. 


File  Using  [N2] 


000001 
000002 
000003 
000004 
000005 
000006 


Now  is  the 
time  for  all 
good  persons 
to  come  to 
the  aid  of 
their  party. 


[O]  Transfer  object  code  files  or  other  non-ASCII  files 

Use  the  [O]  option  when  copying  from  non-ASCII  files  (such  as 
program,  object  code,  or  binary  data  files)  or  from  devices  sending 
non-ASCII  data.  Specifying  the  [O]  option  is  not  necessary  when 
copying  from  files  with  the  COM  type,  because  PIP  assumes  that 
COM-type  files  are  non-ASCII  (non-text)  files. 

Use  of  [O]  tells  pip  to  treat  CTRL-Z  (1 A  hex)  just  like  any  other 
character  it  receives  from  a  source  device  or  file;  PIP  would  other- 
wise interpret  CTRL-Z  as  signaling  the  end  of  the  transfer  from  that 
source. 
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The  following  paragraphs  contain  more  detailed  information 
about  ASCII  files,  non-ASCII  files,  and  end-of-file  markers.  Read 
on  if  you  are  interested  in  these  details. 

PIP  assumes  that  a  CTRL-Z  character  received  from  an  ASCII 
source  (device  or  file)  is  an  end-of-file  marker  or  data  terminator, 
meaning  that  all  the  data  has  been  transferred.  PIP  sends  a  CTRL-Z 
character  to  an  ASCII  destination  (file  or  device)  to  indicate  that  all 
the  data  has  been  sent. 

CP/M  uses  different  methods  for  marking  (and  detecting)  the 
end  of  ASCII  and  non-ASCII  files.  CP/M  marks  the  end  of  an 
ASCII  file  by  placing  a  CTRL-Z  character  in  the  file  after  the  last 
data  character,  unless  the  file  happens  to  contain  an  exact  multiple 
of  128  characters,  in  which  case  adding  the  CTRL-Z  would  waste  127 
characters,  so  CP/M  does  not  do  so.  Use  of  the  CTRL-Z  character  as 
the  end-of-file  marker  is  possible  because  CTRL-Z  is  seldom  used  as 
data  in  ASCII  files. 

In  a  non-ASCII  file,  however,  CTRL-Z  is  just  as  likely  to  occur 
as  any  other  character.  Therefore,  it  cannot  be  used  as  the  end-of- 
file  marker.  CP/M  assumes  it  has  reached  the  end  of  the  file  when  it 
has  read  the  last  record  (basic  unit  of  disk  space)  allocated  to  the 
file.  The  disk  directory  entry  for  each  file  contains  a  list  of  the  disk 
records  allocated  to  that  file.  This  method  relies  on  the  size  of  the 
file,  rather  than  its  contents,  to  locate  the  end  of  the  file. 

[Pn\  Issue  a  form  feed  after  the  nth  line 

Use  [Prc]  when  the  destination  is  the  LST:  device  and  the  current 
LST:  device  (usually  a  printer)  does  not  print  the  source  data  in  the 
following  format: 

•  Top  margin  is  blank 

•  Bottom  margin  is  blank 

•  Top  and  bottom  margins  together  total  six  lines 

•  Text  fills  the  space  between  top  and  bottom  margins 

Deviation  from  these  conditions  usually  occurs  when  the  cur- 
rent LST:  device  has  one  of  the  following  characteristics: 

•  Does  not  understand  the  form  feed  character  (see  [F]) 

•  Does  not  insert  top  and  bottom  margins 

•  Is  printing  on  a  different  length  page  than  that  assumed  by 
the  source  data 

[Pn]  tells  PIP  you  want  it  to  insert  a  form  feed  after  each  n  line  of 
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data.  Enter  the  desired  number  of  lines  in  place  of  n  in  the  PIP 
command  line  option  [Pn\.  Here  n  is  a  decimal  number  in  the  range 
1  through  255,  inclusive.  If  you  do  not  enter  a  number  or  if  the 
number  is  1,  PIP  assumes  you  want  a  page  eject  after  each  60  lines. 

If  [F]  is  also  present  in  the  option  field,  all  form  feeds  detected 
during  the  transfer  will  be  removed,  and  PIP  will  then  insert  new 
form  feeds  as  specified  by  [Pri].  In  other  words,  [F]  and  [P«]  used 
together  will  override  the  paging  implied  by  the  presence  of  form 
feed  characters  in  the  source  data. 

A  printer  that  understands  the  form  feed  character  responds  to 
it  by  immediately  advancing  the  paper  to  the  top  of  the  next  page, 
whether  or  not  the  current  page  is  full.  Printers  that  do  not  under- 
stand the  form  feed  character  may  perform  erratically. 

(See  the  section  on  the  PIP  PRN:  device.) 

[QstringAZ]  Copy  a  portion  of  the  file  up  to  string 

Use  of  the  [Q]  option  allows  you  to  tell  PIP  to  look  for  a  set  of 
characters  and  terminate  the  copying  of  data  when  the  set  is  encoun- 
tered. Select  the  terminating  string  of  characters  carefully;  they 
must  be  unique  to  ensure  that  you  are  copying  the  exact  portion  of 
the  file  desired.  Q  marks  the  beginning  of  the  string,  and  CTRL-Z 
marks  the  end  of  the  string. 

The  string  following  the  Q  option  is  converted  to  uppercase  if 
the  command  line  is  typed  after  the  CP/M  prompt  (A>).  If  the 
command  is  typed  after  the  PIP  prompt  (*),  then  the  automatic 
conversion  does  not  occur.  To  include  lowercase  letters  in  the  string, 
your  command  line  must  follow  the  PIP  prompt.  (See  also  the  [S] 
parameter.) 

[R]  Allow  PIP  to  copy  a  system  file 

Only  by  appending  the  command  line  with  [R]  can  you  copy  system 
files.  The  system  file  attribute,  if  present,  is  copied. 

[SstringAZ]  Copy  the  portion  of  data  beginning  with  string 

Like  the  [Q]  option,  the  [S]  option  specifies  that  you  wish  to  copy 
only  a  portion  of  a  file  using  PIP,  this  time  beginning  at  the  point 
where  PIP  detects  the  string  of  characters  specified  immediately 
following  the  S,  where  string  is  the  sequence  of  characters  to  search 
for  and  AZ  is  a  CTRL-Z  used  to  terminate  the  string.  Both  the  [S]  and 
[Q]  options  may  be  present  on  the  same  command  line. 

See  the  important  explanation  of  automatic  lowercase-to- 
uppercase  conversion  under  the  [Q]  option,  given  previously. 
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[T/i]  Set  tab  stops  every  nth  column 

[Tfl]  tells  PIP  to  expand  any  tab  character  (09  hex  or  CTRL-I)  it 
detects  to  the  number  of  spaces  necessary  to  reach  the  next  tab  stop. 
This  is  useful  as  some  editor  programs  do  not  save  tabs  as  spaces  but 
as  tab  characters,  and  not  all  printers  or  terminals  are  set  up  to 
detect  tab  characters  and  expand  them  to  the  number  of  spaces  they 
represent.  Use  [T77]  to  change  the  standard  tabbing  from  eight 
characters  (or  whatever  your  console  or  printer  defaults  to)  to  a 
number  you  define. 

[U]  Translate  lowercase  to  uppercase 

The  U  option  causes  all  information  in  lowercase  characters  to  be 
translated  into  uppercase  characters  during  the  transfer  process. 

[V]  Verify  the  copy  is  correct  by  comparing  the  memory  buffer  with  the 

newly  created  file  or  files 
The  destination  must  be  a  disk  file;  if  it  is  not,  [V]  is  ignored.  After 
the  transfer  is  complete,  the  destination  is  reread  and  compared  to 
the  data  in  PIP's  memory  buffer.  This  means  that  the  [V]  parameter 
will  catch  errors  in  writing  the  file,  but  not  in  reading  it. 

When  concatenating  several  sources,  the  [V]  option  must  fol- 
low the  first  source  name;  only  one  [V]  is  necessary. 

(Note  that  Gary  Kildall,  creator  of  CP/M,  never  uses  the  [V] 
parameter,  and  members  of  the  Digital  Research  staff  indicate  that 
in  four  years  they  have  yet  to  see  a  verify  error  that  is  not  accompan- 
ied by  a  BDOS  ERR  ON  d:BAD  SECTOR  error.  Therefore,  it  is 
doubtful  that  the  [V]  parameter  will  prove  effective  in  catching 
otherwise  unseen  errors.) 

[W]  Allow  PIP  to  copy  into  a  file  with  the  R/O  attribute 

Since  [W]  permits  you  to  write  to  an  R/O  file,  verifying  this 
attribute  is  no  longer  required  before  proceeding.  If  you  attempt  to 
write  to  an  R  /  O  file  without  using  the  [W]  attribute,  you  receive  the 
message  DESTINATION  FILE  IS  R/O,  DELETE  (Y/N)? 

[Z]  Zero  the  parity  bit  during  the  transfer 

Use  the  [Z]  option  to  set  the  unused  eighth  bit  of  a  character  to  zero 
when  receiving  ASCII  characters  from  a  device.  Each  ASCII  char- 
acter uses  seven  of  the  eight  bits  that  are  processed  by  the  computer. 
The  eighth  bit  is  sometimes  called  the  parity  bit.  To  avoid  myste- 
rious problems  when  processing  ASCII  data,  you  will  usually  find  it 
wise  to  set  the  unused  bit  to  zero. 
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Special  PIP  Devices 

EOF:  Send  an  end-of-file  marker  to  the  destination  device 

When  copying  between  two  ASCII-type  disk  files,  an  end-of-file 
marker  is  automatically  sent  to  the  destination  device.  In  some 
special  instances,  EOF:  can  be  used  to  terminate  the  transfer.  When 
sending  files  from  one  computer  to  another,  it  is  often  necessary  to 
terminate  the  transfer  by  sending  the  EOF:  device  character. 

NUL:  Send  40  null  (do-nothing)  characters  to  the  destination  device 
NUL:  was  originally  used  to  terminate  punched  output  with  a 
blank  section  of  paper  tape;  it  provided  a  header  or  trailer  to  the 
actual  information,  useful  for  threading  purposes.  NUL:  will  pro- 
duce a  4-inch  length  of  blank  paper  tape.  The  ASCII  null  character 
is  called  "Null"  and  is  equivalent  to  00  hex,  or  CTRL-@. 

PRN:  Send  data  to  LST:  device  with  special  instructions 

The  PRN:  device  specifies  additional  instructions  to  the  LST: 
device.  It  expands  tabs,  numbers  lines,  and  paginates  the  copy.  Tab 
stops  are  assumed  at  every  eighth  column.  Every  time  a  tab  charac- 
ter is  detected,  PIP  inserts  spaces  instead;  all  lines  are  numbered 
(beginning  at  1  and  continuing  sequentially  throughout  the  trans- 
fer); page  ejects  are  sent  to  the  printer  every  60  lines  (giving  a  margin 
of  three  lines  at  the  top  and  bottom  of  a  normal  11 -inch  piece  of 
paper).  PRN:  is  used  for  program  development  and  for  listing  the 
contents  of  an  ASCII-type  file;  the  line  numbers  provide  recogniz- 
able reference  points  within  the  file.  PRN:  is  equivalent  to  [NPT8]. 

Examples  of  PIP  Use 

On  the  following  pages,  each  PIP  command  line  parameter  and  option  is 
illustrated  with  an  explanation  of  the  computer  display.  You  may  want  to 
explore  the  possible  combinations  of  PIP  command  lines  and  options,  and 
the  resulting  variations  on  the  uses  previously  listed. 

When  you  see  the  PIP  prompt  (*),  you  may  enter  a  valid  PIP  command 
line  or  press  RETURN  or  CTRL-C  to  return  to  CP/M. 

A>PIP 

The  following  example  shows  a  simple  use  of  the  PIP  command  to  copy  a 
file  into  a  new  file  with  a  new  name. 
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B>PIP  A: LETTER2. DOC=B: LETTER 1  -  DOC 

B> 

Another  simple  use  of  the  copying  aspect  of  the  PIP  command  is  used 
here  to  copy  a  file  between  disks  A:  and  B:. 

B>PIP  LETTER2. DOC=LETTERl . DOC 

B> 

This  next  example  shows  the  use  of  an  option  —  in  this  case,  the  V 
(Verify)  option. 

B > P I P  LETTER2 . DOC=LETTER 1 -  DOC  C  V 3 

B> 

The  next  two  examples  use  the  shorthand  method  of  specifying  a  file 
name  when  the  same  name  will  be  used  on  both  drives.  Either  side  of  the 
equal  sign  may  be  abbreviated  to  just  the  drive  identifier. 

A>PIP  B:=A: DOCUMENT. LETCV3 

A> 

A>PIP  B: DOCUMENT. LET=A: CV 3 

A> 

This  example  uses  both  the  abbreviation  method  (B:=)  and  ambiguous 
file  references  (A:*.*).  When  ambiguous  file  references  are  used,  PIP  reports 
the  names  of  the  files  that  match  your  request  as  it  copies  them. 

A>PIP  B:=A:*.*CV] 
COPYING- 
DOC.  ONE 
DOC. TWO 
LET. ONE 
A> 

The  preceding  example  combines  the  data  in  the  files  JUNE  and  JULY 
(in  that  order)  into  a  new  file  named  DOC. 

A>PIP  B:DOC=A: JUNECV3. A: JULY 

A> 

The  following  example  would  send  a  copy  of  the  file  LAFFERTY.RT  to 
the  LST:  device. 

NOTE:  You  may  not  use  ambiguous  file  references  to  send  a  series  of 
files  to  the  LST:  device. 

B>PIP  LST: =B: LAFFERTY.RT 

B> 
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Acceptable  destination  devices  are  the  following: 


Device  Description 

AUX:  CON:  LST  Logical 

(varies  with  implementation)  Physical 

PRN:  Special 


This  example  creates  a  file  directly  from  information  typed  at  the  console 
device  (up  to  and  including  the  terminating  CTRL-Z). 

B>PIP 

*B : DOCUMENT . MAY=CON : 
*-C 

B> 

Acceptable  source  devices  are  the  following: 


Device  Description 

AUX:  CON:  Logical 

(varies  with  implementation)  Physical 

NUL:  EOF:  Special 


This  example  asks  for  the  data  being  read  from  the  paper  tape  reader  to 
be  copied  to  the  console  display.  In  addition,  it  specified  the  option  of 
converting  information  to  all  uppercase  characters  ([U]). 

A>PIP  CON:=PTR:  CUD 

THIS    IS   A  PAPER  TAPE  READING  DATA 

INTO  THE  SYSTEM,    WHICH  DISPLAYS  IT 

ON   THE   DESTINATION  DEVICE,    THE  CONSOLE. 

A> 


SUBMIT 

Command  Line  Automation 

SUBMIT  directs  the  sequential  entry  and  execution  of  a  number  of 
CP/M  commands  without  additional  operator  response.  To  utilize  SUBMIT, 
you  must  first  create  a  file  with  the  .SUB  file  type,  using  the  CP/M  editor  or 
another  editor.  The  file  you  create  should  contain  the  list  of  CP/  M  commands 
to  be  executed,  in  the  order  you  wish  them  performed,  one  to  a  line. 

SUBMIT  can  provide  a  link  to  the  BACKUP  or  DISKCOPY  program, 
for  instance,  every  time  you  finish  using  a  program.  First,  create  a  SUBMIT 
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file  named  ORREPENT.SUB  that  only  has  these  two  hypothetical  com- 
mands in  it: 

RUN  YOURPROG.RAM 
BACKUP 

(The  RUN  YOURPROG.RAM  can  be  any  valid  CP/M  command,  you 
should  substitute  the  name  of  your  copying  program  for  BACKUP.) 

Next,  run  YOURPROG.RAM  by  typing  SUBMIT  ORREPENT  instead 
of  the  usual  RUN  YOURPROG.RAM  when  you  finish  using  your  program 
and  attempt  to  return  to  CP/M,  the  SUBMIT  facility  will  whisk  you  to  the 
backup  program,  forcing  you  to  duplicate  your  disk  every  time  you  run 
YOURPROG.RAM. 

Program  developers  often  use  a  compiler  rather  than  an  interpreter  to 
write  programs.  A  compiled  program  requires  an  extra  process:  the  actual 
compilation.  In  small  business  packages,  there  may  be  five,  ten,  or  more 
related  program  modules,  all  of  which  need  compiling.  The  compilation 
process  could  take  as  much  as  an  hour  or  more;  the  SUBMIT  facility 
performs  this  function  and  frees  the  programmer  from  having  to  sit  and  type 
each  compilation  command  individually. 

SUBMIT  sequences  can  be  chained  (linked  together)  by  including  a 
normal  SUBMIT  command  line  of  the  following  formats  as  the  last  line  in  a 
.SUB  file. 

SUBMIT  filename 

Creates  a  file  $$$.SUB  that  contains  the  commands  listed  in  file- 
name.and  executes  commands  from  this  file  rather  than  from 
the  keyboard. 

If  you  have  created  a  file  named  NUCLEAR. SUB  that  contains 

STAT  *.BAS 
ERA  *.BAS 
DIR  *.BAS 

when  you  submit  this  file  for  execution,  the  dialog  will  look  like  this: 

A>SUBMIT  NUCLEAR 
A > STAT  *.BAS 

RECS  BYTS  EX  D: FILENAME. TYP 

2  4K        1   A: PORGY. BAB 

4         8K        1   A: PORKY. BAS 

8        17K       2  A: PORTLY. BAS 
BYTES  REMAINING  ON  A:    151 K 
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A>ERA  *.BAS 
A > D I R  *.BAS 
NO  FILE 

A> 

The  commands  following  SUBMIT  are  typed  by  CP/M,  not  you.  The  only 
thing  you  typed  in  sequence  is  this: 

SUBMIT  NUCLEAR 

Press  any  key  to  stop  the  execution  in  between  SUBMIT  file  commands; 
that  is,  just  before  the  prompt  is  displayed. 

SUBMIT  filename  ABC 

Creates  a  file  $$$.SUB  that  contains  the  commands  listed  in  file- 
name. SUB  and  executes  commands  from  this  file,  rather  than  from 
the  keyboard. 

This  form  of  the  SUBMIT  command  differs  from  the  previous  one  in 
that  you  may  include  incomplete  CP/M  command  lines  in  the  file  file- 
name. SUB  when  you  create  it.  SUBMIT  fills  in  the  missing  information  using 
the  A,  B,  C,  and  so  on  from  the  command  line  you  type  when  you  start 
SUBMIT.  These  parameters  can  be  filenames  or  any  other  information 
needed  by  the  commands  in  filename.  SUB.  The  symbols  $  1 ,  $2,  $3,  and  so  on 
should  be  used  in  your  SUBMIT  file  to  hold  the  place  for  the  missing 
parameters.  Up  to  nine  parameters  may  be  used. 

Suppose  that  you  are  editing  a  file  on  drive  A  and  you  want  to  copy  it  to 
drive  B,  then  check  disk  space  each  time  you  finish  an  editing  session. 
Without  SUBMIT,  you  would  enter  the  following  command  lines  in  the 
course  of  your  work  (intervening  ED  commands  and  other  dialog  are  omitted 
for  clarity): 

A>ED  MYFILE.DOC 

A>PIP  B:=A:MYFILE-DOCCV3 

A>STAT  B: MYFILE.  * 

Suppose  also  that  you  use  this  method  with  every  file  you  edit,  not  just 
with  MYFILE.DOC.  To  make  SUBMIT  do  the  typing  for  you,  first  create  a 
.SUB  file  named  WORKON  (for  example)  containing  the  incomplete  com- 
mands listed  here: 

ED  $1.$2 

PIP  B:=A:$1.$2 

STAT  B:l$.* 
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To  use  this  SUB  file  as  outlined,  type  this  command  line: 

A>SUBMIT  WORKON  MYFILE  DOC 

SUBMIT  will  create  $$$.SUB  from  WORKON. SUB  by  substituting  the  first 
parameter,  MYFILE,  for  $l  each  time  it  appears  and  the  second  parameter, 
DOC,  for  $2  each  time  it  appears.  SUBMIT  then  initiates  a  warm  start,  and 
CP/M  looks  for  the  file  $$$.SUB.  It  then  executes  the  commands  listed  in 
$$$.SUB. 

PROFILE.SUB 

CP/M-PLUS  looks  for  a  special  file,  named  PROFILE.SUB,  which  will 
be  automatically  executed  after  every  cold  boot  or  system  reset.  By  placing 
commands  in  PROFILE.SUB,  you  can  tailor  a  series  of  routines  that  are 
automatically  triggered  each  time  you  start  the  computer.  Many  users  put  a 
DATE  and  SETDEF  command  in  their  PROFILE.SUB  file,  since  these 
commands  are  usually  only  used  once  at  the  beginning  of  each  computer 
session. 

DATE 

Set  or  Display  the  Date 

DATE  keeps  track  of  the  time  and  day.  This  process  is  done  automati- 
cally after  you  enter  the  time  and  date  each  time  you  start  up  the  system. 
The  forms  of  the  DATE  command  are 

DATE  CONTINUOUS 
DATE  C 

Causes  the  system  to  display  the  date  and  time  continuously  until 
any  key  is  pressed. 

DATE  SET 

DATE  mmlddlyy  hh:mm:ss 
where: 

mm  represents  a  month  ( l  -12) 

dd  represents  a  day  (1-31) 

yy  represents  a  year  (00-99);  the  19  is  assumed 

hh  represents  an  hour  (0-23)  (military  time) 

mm  represents  a  minute  (0-59) 

ss  represents  a  second  (0-59). 
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Allows  the  user  to  set  the  date  and  time,  with  the  first  version  prompting  the 
user  for  the  date  and  time,  and  the  second  simply  setting  it.  NOTE:  The  time 
and  date  are  not  actually  set  until  the  user  presses  a  key  in  response  to  the 
prompt  Press  any  key  to  set  time. 

The  following  example  shows  the  continuous  display  of  the  time. 
Observe  how  pressing  a  key  interrupts  the  display. 

a > date  c 

Mon  10/03/33  10:30:01 
Mon  1 O / 03 / 33  1 O : 30 : ) @ 
Mon  10/03/83  10:30:03 
A> 

This  example  shows  the  prompting  for  the  date  and  time  that 
CP/M-PLUS  displays  when  you  ask  to  set  the  time: 

A>DATE  SET 

Enter  today's  date    (MM/DD/YY)  :  10/01/83 
Enter  the   time    (HH:MM:SS:):  04:10:00 
press  any  key  to  set  time 

A> 

This  last  example  shows  how  to  set  the  time  without  prompting  from 
CP/M-PLUS: 

A>DATE   10/01/83  04:10:00 
Press  any  key  to  set  time 

A> 


DEVICE 


Display  and  Assign  Devices 

The  DEVICE  transient  command  is  CP/M-PLUS's  equivalent  to  the  use 
of  STAT  for  displaying  the  current  status  of  devices  and  assigning  them.  The 
following  shows  the  logical  device  names  under  CP/M-PLUS: 

CP/M-PLUS  Name 

CON:  or  CONSOLE: 
CONIN:  or  KEYBOARD: 
CONOUT: 

AUX:  or  AUXILIARY: 

AUXIN: 

AUXOUT: 


LST:  or  PRINTER 
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In  addition  to  being  able  to  assign  any  logical  device  to  a  particular 
physical  device,  CP/M-PLUS  allows  you  to  assign  certain  parameters  to  each 
of  the  devices: 

Parameter  Device 

I  Device  is  input 

O  Device  is  output 

S  Device  is  serial 

X  Device  uses  X-ON/  X-OFF 

communications  protocol 

The  following  are  the  allowable  forms  of  the  DEVICE  command: 

DEVICE 

Displays  the  current  assignments  and  then  prompts  for  a  new 
assignment. 

DEVICE  NAMES 

Displays  the  allowable  physical  device  names. 

DEVICE  VALUES 

Displays  the  current  logical  device  assignments. 

DEVICE  CONSOLE  [options] 

Displays  the  current  console  page  width  in  columns  and  the  page 
length  in  lines  if  the  option  is  PAGE;  sets  the  number  of  columns  to 
the  number  indicated  if  the  option  is  COLUMNS=/?:  sets  the 
number  of  lines  assumed  to  be  on  the  console  device  if  the  option  is 
LINES=«. 

DEVICE  device 

Displays  the  current  assignment  for  the  device  requested. 

DEVICE  logicaldevice=physicaldevice[options] 

Assigns  the  logical  device  to  the  physical  device  indicated,  with  the 
options  in  effect  as  specified. 

DEVICE  logicaldevice=physicall[options],physical2[options] 

Multiple  physical  devices  can  be  attached  to  a  single  logical  device 
by  separating  each  assignment  with  a  comma  on  the  command  line. 

DEVICE  logicaldevice=NULL 

Unassigns  the  logical  device  from  its  previous  physical  device 
assignment. 


There  are  three  options  available  for  DEVICE. 
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[XON] 

Sets  the  device  to  communicate  using  a  standard  data  exchange 
protocol  known  as  XON/XOFF.  Before  each  character  is  output 
from  CP/M-PLUS  to  the  device,  CP/M-PLUS  checks  to  see  if  there 
is  any  incoming  data  from  the  device.  If  there  is  and  if  that  data 
corresponds  to  the  XOFF  character,  CP/M-PLUS  stops  sending 
information  until  it  sees  an  XON  character  from  the  device. 

[NOXON] 

Indicates  that  no  protocol  is  to  be  used;  CP/M-PLUS  will  send  data 
whether  or  not  the  device  is  ready  to  receive. 

[«] 

A  baud  rate  (for  serial-type  devices  only)  that  indicates  the  speed  at 
which  information  is  to  be  sent  and  received.  The  number  n  must  be 
one  of  the  following  to  be  valid: 

50         75         110        134       150       300       600  1200 
1800      2400      3600     4800      7200      9600  19200 

In  the  following  example,  DEVICE  first  gives  a  summary  of  the  current 
devices  and  their  assignments,  and  then  prompts  the  user  for  a  new  assign- 
ment: the  user  indicates  that  the  LST:  device  should  be  attached  to  the  CEN: 
physical  device  instead  of  its  current  setting,  PRNTR. 

A>DEVICE 

Physical  Devices: 

I  =  Input,  0=Output,  X=Serial,  X  =  Xon-Xo-f-F 

CRT  NONE  IO       CEN     NONE  O         MODEM     300  IO 

PRNTR       9600   IOSX    IEEE  NONE  IO 

Current  Assignments: 

CONIN:      =  CRT 

CONOUT:    =  CRT 

AUXIN:      =  MODEM 

AUXOUT:    =  MODEM 

LST:  =  PRNTR 

Enter  new  assignment  or  hit  RETURN:  LST:=CEN: 

The  following  illustration  shows  two  forms  of  assigning  devices  with  the 
DEVICE  command.  The  first  attaches  both  the  PRNTR  and  CRT  physical 
devices  to  the  CONOUT:  logical  device  (output  will  go  to  both  display  and 
printer);  the  second  attaches  the  physical  device,  MODEM,  to  the  logical 
device,  AUXIN:,  setting  MODEM  for  300-baud  transmission  and  no 
XON/XOFF  protocol. 

A>DEVICE  CONOUT: =PRNTR. CRT 

A > DE V I CE  AUX IN: =MODEM C NOXON, 300 1 
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The  following  example  first  examines  the  console  setting  to  see  the 
number  of  columns  and  lines  CP/M-PLUS  is  currently  using  when  output- 
ting  information  to  the  console.  Next  these  parameters  are  reset,  in  this  case  to 
52  columns  of  24  characters  each. 

A> DEVICE. CONSOLE   C PAGE 3 

Console:    Columns  =  80,    Lines  =  25 

A>DEVICE  CONSOLE   CC0LUMNS=52, LINES=24  3 

A> 

GET 

Get  Program  Input  From  Disk  File 

The  GET  command  is  similar  in  some  respects  to  SUBMIT,  but  unlike 
SUBMIT,  it  represents  what  is  known  as  true  I/O  redirection  (input  comes 
from  a  source  other  than  the  keyboard,  in  this  case,  a  disk  file).  The  practical 
differences  between  batch  processing  and  I/O  redirection  are  few;  the  pri- 
mary difference  you  will  observe  is  that  SUBMIT  builds  an  extra,  temporary 
file,  while  GET  does  not  require  the  extra  file. 

GET  is  handy  for  automatically  running  programs,  or  portions  of  pro- 
grams, that  require  the  same  input  each  time  they  are  used.  GET  is  especially 
handy  for  getting  around  annoying  or  repetitive  requests  that  sometimes 
occur  at  the  beginning  of  many  programs,  as  you  will  see  in  the  examples 
given  later. 

GET  CONSOLE  INPUT  FROM  FILE  filename  .typ 

GET  FILE  filename,  typ 

These  two  forms  of  the  GET  command  are  the  same,  since  the 
words  CONSOLE  INPUT  FROM  are  optional.  Console  input 
from  the  file  begins  immediately  after  the  next  system  command  is 
typed  and  terminates  when  the  end  of  the  input  file  is  reached  or  the 
next  CP/M-PLUS  system  prompt  appears  (for  instance,  A>). 

GET  CONSOLE  INPUT  FROM  Y\LE  filename. typ\options\ 
GET  FILE  filename.  typ[options] 

Invokes  GET,  as  shown  earlier,  but  with  a  specified  option  or 

options. 

Here  are  the  options  for  GET. 
[ECHO] 

All  input  from  the  file  will  be  displayed  on  the  console,  as  if  you  had 
typed  it.  ECHO  is  the  default  setting. 
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[NO  ECHO] 

No  display  of  information  from  the  input  file  will  be  made  on  the 
console. 

[SYSTEM] 

Indicates  that  all  input  —  both  at  the  CP/  M-PLUS  system  level  and 
the  program  level  —  is  to  be  taken  from  the  file.  If  not  specified, 
GET  only  retrieves  information  from  the  file  at  the  program  level 
and  terminates  execution  at  the  system  level.  The  SYSTEM  option 
takes  effect  immediately;  you  are  not  returned  to  the  CP/ M-PLUS 
prompt  until  all  the  information  in  the  input  file  is  exhausted  or 
until  a  GET  instruction  is  read  from  the  input  file  (which  cancels  the 
SYSTEM  option). 

The  following  is  a  simple  example  of  using  GET  in  the  usual,  default 
fashion: 

A>GET  CONSOLE   INPUT  FROM  FILE  FOLDER, 1 

A>PIP 

PIP  3.0 

*B: =A: *. FAS <cr  > 
*B: =A: * - BAK<cr> 
*<cr> 
A> 

The  file  FOLDER.  1  contains  the  following: 

B:=A:*.BAS<cr> 
B:=A:*.BAK<cr> 

<cr> 

In  the  next  example,  the  instructions  in  FOLDER. 2  are  used  to  initiate  a 
WordStar  editing  session,  first  starting  the  program,  then  logging  onto  drive 
B,  and  then  getting  to  the  "Name  of  document  file  to  edit?"  prompt.  All  you 
have  to  do  is  supply  the  name  of  the  file,  and  you  can  begin  editing 
immediately. 

A >GET  FILE  FOLDER.  2  C SYSTEM D      [New  Word  signs  on  and  displays  menu] 

A>NW 

L 

The  logged  disk  drive  is  where  New  Word  will   get  a  document  if 
you  do  not  specify  a  drive  letter  when  you  enter  a  document  name. 


The  logged   disk  is  currently:  A 

Legal   drives  are:   A  B  [New  Word  redisplays  menu] 
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What  would   you   like  the  new  logged  drive  to  be?  B: 
D 

Document? 

The  FOLDER. 2  file  looks  like  this: 

NW<cr> 
LB:<cr> 
D 

Since  the  file  is  exhausted  after  the  D,  you  are  left  to  use  New  Word  in  the 
normal  fashion  (from  the  keyboard). 

Even  more  cleverly,  the  GET  command  could  be  made  part  of  a  PRO- 
FILE. SUB  file  that  is  invoked  upon  starting  the  system. 

HELP 

Display  Information  About  Various  Subjects 

The  HELP  transient  command  is  really  a  program  that  allows  you  to 
receive  information  about  most  CP/M-PLUS  subjects  —  it  is  an  on-line  or 
specific  information,  depending  on  how  you  phrase  your  help  request.  Digital 
Research  supplies  a  basic  HELP  file  (HELP.HLP)  that  covers  CP/M-PLUS, 
but  you  may  add  help  information  of  your  own  by  using  the  special  features  of 
HELP. 

HELP 

Invokes  HELP  and  presents  a  menu  of  topics  to  choose  from. 
HELP  displays  a  prompt  of  HELP>,  to  which  you  may  reply  with  a 
topic  name  or  a  subtopic  name  preceded  by  a  period. 

HELP  topic 

Invokes  HELP  and  presents  information  on  the  chosen  topic. 

HELP  topic  subtopic 

Invokes  HELP  and  presents  information  on  the  chosen  subtopic 
within  the  topic.  Additional  subtopics  may  be  added  following  the 
first,  each  separated  by  a  space. 

Each  form  of  the  HELP  program  can  be  used  with  the  following  options 
(appearing  at  the  end  of  the  command  line). 

[NO  PAGE] 

Disables  the  default  paged  display  of  information.  To  stop  the 
display,  use  CTRL-S;  to  resume  use  CTRL-Q.  NO  PAGE  may  be 
abbreviated  to  N. 
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[LIST] 

Is  the  same  as  [NO  PAGE]  except  that  extra  lines  between  topic 
headings  are  removed.  This  option  is  useful  for  conserving  paper  if 
you  are  also  printing  out  the  HELP  using  CTRL-P. 

Other  forms  of  the  HELP  command  are 

HELP  [EXTRACT] 

Takes  data  from  the  HELP.HLP  file  and  copies  it  into  a  file  named 
HELP. DAT,  which  may  be  edited  using  ED  or  any  other  text  editor. 
EXTRACT  may  be  abbreviated  to  E. 

HELP  [CREATE] 

Performs  the  reverse  process  of  the  EXTRACT  option,  taking 
information  from  HELP.DAT  and  creating  a  new  HELP.HLP  file. 
CREATE  may  be  abbreviated  to  C. 

HELP.DAT  files  have  the  following  form: 

•  Topics  are  placed  in  alphabetical  order. 

•  Subtopics  are  in  alphabetical  order  within  topic. 

•  Topic  and  Subtopic  levels  are  indicated  with  a  number  from  1  to  9. 

•  Each  topic  and  subtopic  text  is  preceded  by  a  topic  heading,  in  the 
format  rcTOPIC,  where  n  is  the  topic  level  (1  being  a  topic,  9  being  the 
lowest  subtopic)  and  TOPIC  is  the  topic  name  you  select. 

•  Each  topic  name  should  be  unique. 

•  Topic  names  can  be  up  to  12  characters  in  length. 

This  example  shows  how  to  invoke  HELP  without  asking  for  a  specific 
topic: 

A. HELP 

Help   isavailable  -for: 

DIR  DIRSYS  RENAME  ERASE  SAVE  TYPE 

Help>DIR 

DIR   is  the  directory  command-- 

This  example  shows  how  typing  a  topic  name  takes  you  directly  to  the 
information  for  that  topic: 

A > HELP  DIR 

DIR   is  the  directory  command.... 
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INITDIR 

Initialize  Time  and  Date  Stamping 

The  SET  command,  described  later  in  this  chapter,  allows  time  and  data 
stamping  of  files  under  CP/M-PLUS.  The  INITDIR  command  is  initially 
used  to  modify  the  directory  entries  so  they  are  capable  of  storing  the  time  and 
date  stamping. 

INITDIR  is  a  simple  program  that  performs  only  a  single  function: 
rearranging  the  directory  for  use  with  or  without  time  and  date  stamping. 
The  allowable  form  of  the  INITDIR  command  is 

INITDIR 

or 

INITDIR  d: 

If  time  and  date  stamping  has  not  been  activated  for  the  disk  in  the  drive 
you  specify,  INITDIR  asks  if  you  want  to  reformat  the  directory  for  time  and 
date  stamping. 

A> INITDIR  B: 

INITDIR  WILL  ACTIVATE  TIME  STAMPS  FOR  SPECIFIED  DRIVE. 

Do  you   really  want   to  re— format   the  directory:  B    (Y/N)?  Y<cr> 

If  the  time  and  date  stamping  option  has  already  been  invoked  for  the 
disk  in  question,  INITDR  asks  if  you  want  to  reformat  the  directory  without 
time  and  date  stamping. 

A> INITDIR 

TIME  AND  DATE  STAMPING  IS  ACTIVATED  FOR  SPELIFIED  DRIVE. 
Do  you  want   the  existing  date/time  stamps  cleared    (Y/N) ?  N 

PUT 

Place  Program  Output  in  Disk  File 

PUT  is  the  corollary  to  GET.  Instead  of  retrieving  input  from  a  file,  PUT 
writes  console  or  printer  output  to  a  file  for  later  use.  Try  to  use  PUT  in 
conjunction  with  GET,  so  that  if  anything  unusual  happens  during  a  GET- 
automated  session,  you  will  be  able  to  go  back  to  review  what  happened  from 
the  file  that  PUT  created. 
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PUT  CONSOLE  OUTPUT  TO  FILE  filename  Jyp[options] 

PUT  CONSOLE  FILE  filename.  typ[options] 

These  are  two  equivalent  PUT  commands  that  direct  all  console 
output  to  the  named  file.  Console  output  is  redirected  to  the  file 
until  the  program  terminates. 

PUT  CONSOLE  OUTPUT  TO  CONSOLE 
PUT  CONSOLE  CONSOLE 

Redirects  console  output  to  the  console  instead  of  a  file  (restores 
normal  operations). 

PUT  PRINTER  OUTPUT  TO  FILE  filename.  typ[options\ 

PUT  PRINTER  FILE  filename. typ[options\ 

Sends  all  output  normally  destined  for  the  list  device  to  the  named 
file.  Printer  output  is  redirected  to  the  file  until  the  program 
terminates. 

PUT  PRINTER  OUTPUT  TO  PRINTER 
PUT  PRINTER  PRINTER 

Redirects  printer  output  to  the  printer  instead  of  a  file  (restores 
normal  operations). 

The  allowable  PUT  options  are  given  here. 

[ECHO] 

Indicates  that  all  output  is  to  be  sent  to  the  console  as  well  as  the  file. 
This  is  the  default  setting. 

[NO  ECHO] 

Indicates  that  all  output  is  to  be  sent  to  the  file  only;  no  output  is 
directed  to  the  console. 

[FILTER] 

Tells  PUT  to  translate  all  control  characters  into  readable  form  (a 
CTRI^C,  for  instance,  is  saved  in  the  file  as  AC). 

[NO  FILTER] 

Tells  PUT  not  to  translate  any  control  or  special  characters  it  sends 
to  the  file.  This  is  the  default  option. 

[SYSTEM] 

Like  GET,  the  SYSTEM  option  indicates  that  I/O  redirection  is  to 
take  place  immediately  and  to  continue  until  a  subsequence  PUT 
CONSOLE  command  is  encountered.  SYSTEM  SENDS  both 
system  and  program  output  to  the  file,  whereas  the  default  sends 
program  output  only. 
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Here  is  an  example  using  the  PUT  command: 

A>PUT  CONSOLE  OUTPUT  TO  FILE  CABINET. 1 C ECHO 1 
A>PIP 

*AUXOUT:=CON: 

This  is  an  example  o-f  sending  something  -from  the 
keyboard  to  the  AUXILARY  device  and  to  a  -file  at 
the  same  time.      Isn't  this  -fun? 

* 

A>TYPE  CABINET. 1 
*AUXOUT:=CON: 

This   is  an  example  o-f  sending  something   -from  the 
keyboard  to  the  AUXILARY  device  and  do  a  -file  at 
the  same  time.      Isn't   this  -fun? 
'  Z 
* 

A> 

This  routine  shows  how  the  console  output  was  saved  by  the  PUT  command 
in  the  file  specified.  The  user  redisplayed  it  by  using  the  TYPE  command  to 
verify  that  PUT  did  save  the  output. 


SET 

Assign  Password,  Time  Stamping, 
Disk  Label,  File  and  Drive 
Attributes 

The  SET  transient  command  allows  the  user  to  do  the  following: 

•  Set  the  file  type  attribute  to  DIR  or  SYS 

•  Set  the  file  type  attribute  to  R/O  or  R/W 

•  Label  a  disk 

•  Set  a  password  for  disk  or  files 

•  Set  password  protection  to  ON  or  OFF 

•  Set  the  time  and  date  stamping  option  to  ON  or  OFF 

•  Set  the  archive  attribute  ON  or  OFF 

•  Set  user-definable  attributes  ON  or  OFF. 

The  following  are  possible  uses  of  the  SET  command: 
SET 

Initiates  the  SET  program  and  prompts  user  for  a  valid  setting. 
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Performs  a  setting  assignment  based  upon  the  options  the  user 
types. 

SET  d:[options] 

Performs  a  setting  assignment  on  the  indicated  disk  based  upon  the 
options  the  user  types. 

SET  d: filename. typ\options\ 

Performs  a  setting  assignment  for  the  specified  file  based  upon  the 
options  the  user  types. 

The  allowable  options  for  SET  are 

[DIR] 

The  [DIR]  option  is  used  with  a  file  specification  to  set  the  file  type 
attribute  for  the  file  (or  files,  if  ambiguous  references  are  used)  to 
DIR,  short  for  Directory.  DIR  files  appear  in  normal  directories, 
but  they  do  not  appear  when  DIRSYS  is  used. 

[SYS] 

The  [SYS]  option  is  used  with  a  file  specification  to  set  the  file  type 
attribute  for  the  file  (or  files,  if  ambiguous  references  are  used)  to 
SYS,  short  for  System.  SYS  files  do  not  appear  in  normal  directo- 
ries; they  appear  when  DIRSYS  is  used. 

[RO] 

[RO]  option  is  used  with  a  file  specification  to  set  the  file  type 
attribute  for  the  file  (or  files,  if  ambiguous  references  are  used)  to 
R/O  short  for  Read-Only.  Read-Only  files  cannot  be  written  to  or 
erased  under  normal  circumstances. 

[RW] 

The  [R /  W]  option  is  used  with  a  file  specification  to  set  the  file  type 
attribute  for  the  file  (or  files,  if  ambiguous  references  are  used)  to 
R/W,  short  for  Read/ Write.  Read /Write  files  can  be  written  to  or 
erased  under  normal  circumstances. 

[ARCHIVED] 

The  ARCHIVE  option  is  used  to  set  the  archive  file  attribute  to  the 
state  s  indicated,  which  must  be  ON  or  OFF.  Files  that  have  the 
archive  bit  set  to  ON  have  not  been  modified  since  they  were  last 
copied  (using  PIP);  files  with  the  bit  set  to  OFF  have  not  been  copied 
since  they  were  last  modified. 
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=s] 
=s] 
=s] 
=s] 

CP/M-PLUS  allows  four  user-definable  file  attribute  bits  to  be  set 
to  the  state  s  indicated,  which  must  be  ON  or  OFF.  The  user  may  use 
these  bits  to  indicate  any  desired  attribute  of  the  file;  CP/M-PLUS 
does  not  use  these  bits  for  any  other  function. 

[NAME=labelname.  typ] 

The  NAME  option  assigns  a  label  (name)  to  the  disk  specified  (if  no 
disk  is  specified,  the  default  disk  is  used).  The  naming  conventions 
for  disk  labels  are  the  same  as  those  of  file  names:  eight  characters  in 
the  name  and  an  optional  three-character  type.  Label  names  can  be 
used  to  keep  track  of  disks  and,  with  proper  assembly  language 
programming,  can  be  used  within  programs  to  check  that  the 
appropriate  disk  is  in  the  drive  before  a  function  is  invoked. 

[PASSWORD=password] 

[PASSWORD^  (NOTE:  No  closing  bracket.) 

CP/M-PLUS  allows  the  user  to  set  passwords  for  an  entire  disk  or 
to  individual  files  on  the  disk.  Passwords  should  be  unique  and 
should  contain  eight  characters  or  less.  If  you  use  passwords,  be 
careful  to  remember  what  they  are,  since  CP/M-PLUS  does  not 
allow  you  to  look  them  up  once  they  are  assigned.  Should  you  forget 
a  file's  password,  you  will  not  be  able  to  use  that  file  anymore. 
Pressing  RETURN  removes  any  current  password  from  a  file  or  disk. 

[PROTECTS] 
[PROTECT^] 

This  option  has  two  forms.  The  first  form  allows  you  to  set  pass- 
word protection  for  all  files  on  the  disk  by  indicating  the  password 
status  s,  which  must  be  ON  or  OFF.  The  second  form  allows  you  to  set 
the  type  /  of  password  protection  for  files,  where  t  is  one  of  the 
following: 

READ  Password  is  required  to  read  from  file. 

WRITE  Password  is  required  to  write  to  file. 

DELETE        Password  is  required  to  delete  the  file. 
NONE  No  password  is  required  for  the  file;  any 

current  password  is  deleted. 


[Fl 

[F3 
[F4 
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[DEFAULT  ^password] 

This  option  sets  a  default  password  for  the  system  to  use  during  the 
current  session  (it  is  temporary,  unlike  the  other  password  options). 

[CREATE^] 
[ACCESS=s] 
[UPDATE=s] 

Date  and  time  stamping  is  controlled  by  three  options  that  may  be 
set  ON  or  OFF  as  desired.  CRE  ATE=ON  turns  on  time  stamping  for 
the  disk.  CREATE=OFF  turns  the  time  stamping  off.  ACCESS 
=ON  time  stamps  files  each  time  they  are  accessed;  ACCESS=OFF 
disables  this  feature.  NOTE:  If  CREATE  is  ON,  then  ACCESS 
must  be  OFF,  and  vice  versa.  Either  CREATE  or  ACCESS  can  be 
ON,  but  not  both.  UPDATE=ON  turns  on  the  time  stamping  func- 
tion each  time  a  file  is  modified;  UPDATE=OFF  disables  this 
feature. 

Note:  You  must  use  INITDIR  on  a  disk  before  activating  the 
time  and  date  stamping  options.  INITDIR  is  described  earlier  in 
this  chapter. 

The  following  example  sets  all  .COM-type  files  to  be  read/ write  and 
system  files: 

A>SET  A:*.COMCRW  SYS 3 

The  following  example  turns  on  the  archive  attribute  and  user-definable 
attribute  1  for  all  files: 

A>SET  A :  * .  ■*  C ARCH I VE=ON  Fl=ON3 

The  following  example  labels  the  disk  in  drive  B  with  the  name 
MYDISK.l: 

A>SET  B: CNAME=MYDISK. 13 

This  example  sets  the  password  for  the  default  disk  to  "opnsesme." 

A>SET  CPASSWORD=opnsesme3 

The  next  example  combines  two  options.  First,  the  password  is  set  for  all 
files  to  DOIT.  Next,  the  system  is  told  that  the  password  should  be  required 
every  time  a  file  is  deleted.  (This  is  a  good  idea  —  you  will  never  accidentally 
erase  a  file  if  you  require  a  password  for  deletion  on  every  disk.) 

A>SET  *.*   CPASSWORD=DOIT  PROTECT=DELETE 3 
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The  following  example  tells  CP/M-PLUS  to  turn  ON  the  date  and  time 
stamping  for  any  access  or  update  of  a  file: 

A>SETCACCESS=ON  UPDATE=ON3 

SETDEF 

Set  Default  Definitions 

One  problem  that  first-time  users  often  have  in  CP/M-PLUS  occurs 
when  they  log  on  to  another  drive  (say  B:)  and  then  type  a  built-in  CP/M- 
PLUS  command  that  has  information  stored  in  a  file  on  drive  A.  The  result  is 
an  error  message,  since  CP/M-PLUS  looks  for  that  file  on  drive  B.  The 
SETDEF  command  corrects  this  problem  by  allowing  the  user  to  specify 
which  disk  drives  are  to  be  searched,  for  what,  and  in  what  order. 

SETDEF  allows  the  user  to  define  (either  for  the  entire  computer  session 
or  until  the  next  SETDEF  instruction)  the  following: 

•  Which  drives  to  search  for  files  and  in  what  order 

•  What  types  of  files  to  search  for  and  in  what  order 

•  Where  to  place  temporary  files  (used  by  ED  and  SUBMIT,  among 
others) 

•  Whether  to  display  information  about  a  file  before  executing  its 
instructions 

•  Whether  to  display  information  on  the  console  in  a  paged  or  nonpaged 
fashion. 

The  allowable  forms  of  the  SETDEF  command  are 
SETDEF 

Displays  the  current  defined  settings  for  disk  search  order,  drive  to 
store  temporary  files,  and  file  type  search  order. 

SETDEF[TEMPORARY=d:] 

Tells  the  system  to  store  all  temporary  files  on  the  disk  drive 
specified. 

SETDEF  d: 

SETDEF  d:,d:,d:,d: 

Tells  the  system  to  search  for  files  on  the  drive  specified  (in  the  first 
case)  or  on  the  drives  specified  (in  the  second  case).  An  *  can  be 
substituted  for  d:  to  represent  the  default  drive.  The  order  in  which 
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drive  names  are  listed  indicates  the  order  in  which  to  search. 

SETDEF[ORDER=^/?,/yp] 

This  command  tells  CP/M-PLUS  to  search  for  the  file  types  in  the 
order  indicated.  The  file  types  can  be  .COM  or  .SUB  only.  This 
facility  is  useful  for  automatically  invoking  the  SUBMIT  facility  if  a 
user  types  the  name  of  a  .SUB-type  file. 

SETDEF[DISPLAY] 
SETDEF[NO  DISPLAY] 

DISPLAY  indicates  that  CP/M-PLUS  is  to  show  the  file  name,  the 
drive  on  which  it  was  found,  the  file  type  (if  any),  and  the  user 
number  (if  not  the  current  user  area)  of  the  file  before  accessing  the 
file.  This  is  useful  for  validating  that  the  file  accessed  is  the  one 
intended.  NO  DISPLAY,  the  default  setting,  turns  this  facility  OFF. 

SETDEF[PAGE] 
SETDEF[NO  PAGE] 

The  PAGE  and  NO  PAGE  options  control  whether  CP/M-PLUS 
stops  after  displaying  one  full  page  of  information  or  continues  to 
scroll  the  screen  when  full.  The  default  setting  is  PAGE. 

The  following  example  sets  the  default  search  order  to  the  default  drive, 
drive  A,  and  drive  B,  in  that  order.  CP/  M-PLUS  will  search  each  of  these  for 
any  future  file  references. 

A>SETDEF  *. A: -B: 

This  example  shows  how  the  DISPLAY  option  shows  the  name  and 
location  of  the  file  before  executing  its  instructions: 

A>SETDEF  CDISPLAY3 
A>COPY 

B:COPY  COM   (User  1) 

The  Whis-Bang  Four  COPY  Program  

This  next  example  tells  CP/M-PLUS  to  look  first  for  a  .COM-type  file 
when  interpreting  command  lines  and  then  to  look  for  a  .SUB-type  file  if  no 
.COM-type  file  is  found. 

A>SETDEJ-    CORDER=COM.  SUB 3 
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SHOW 

Displays  Information  on  Disks 

SHOW  allows  the  user  to  see  the  following  information  concerning  a 

disk: 

•  Access  mode  (R/W  or  R/O)  and  free  space 

•  Disk  label  (user-supplied  name  for  disk) 

•  Current  user  number 

•  Number  of  files  for  each  user  on  disk 

•  Number  of  available  directory  entries  left  on  disk 

•  Drive  characteristics. 

The  SHOW  command  has  one  form: 

SHOW  d:[options] 

This  command  displays  information  where  d:  is  an  optional  disk 
drive  specifier  and  options  are  one  or  more  options  (each  separated 
by  a  space). 

Here  are  some  options  for  SHOW: 

[SPACE] 

The  [SPACE]  option  displays  the  drive  name,  its  access  status,  and 
the  remaining  space  in  Kbytes.  If  no  drive  specifier  was  typed, 
SHOW  displays  the  information  for  all  logged-in  drives  in  the 
system.  The  [SPACE]  option  is  the  default  and  need  not  be  explic- 
itly typed  unless  another  option  is  requested. 

[LABEL] 

The  [LABEL]  option  displays  the  disk's  label  information:  the 
directory  label  (name)  given  the  disk,  whether  passwords  are 
required,  whether  the  date  stamping  option  (see  the  SET  command 
section  in  this  chapter)  is  turned  ON,  and  the  date  when  the  label  was 
created  and  last  updated. 

[USERS] 

The  [USERS]  option  displays  the  current  user  number  and  all  users 
on  the  drive  specified,  as  well  as  the  number  of  files  assigned  to  each 
user.  In  addition,  it  displays  the  number  of  free  directory  entries. 
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[DIR] 

The  [DIR]  option  displays  the  number  of  free  directory  entries  on 
the  specified  drive. 

The  following  example  shows  the  simplest  use  of  the  SHOW  com- 
mand: the  user  has  asked  for  the  status  of  all  logged-in  disk  drives  (in  this 
case,  A  and  B).  Note  that  the  access  mode  of  drive  A  is  read/  write,  while  that 
of  drive  B  is  read-only. 

A>SHOW 

As  RW,  Space:  24k 
B:  RO,  Space:  128k 
A> 

The  next  example  shows  the  label  for  the  disk  in  drive  B.  The  name  of  the 
disk  is  THOM 15;  the  password,  date  stamping  on  creation,  and  date  stamping 
on  file  updating  option  are  ON.  The  label  was  created  at  12:01  on  July  22, 
1983,  and  was  updated  a  week  later. 

A>SHOW  B: C LABEL 1 
Label    -for  drive  B: 

Directory     Passwds       Stamp     Stamp     Label  Created     Label  Updated 
Label  Reqd  Create  Update 

TH0M15  on  on  on  07/22/83   12:01   07/29/83  1:23 

A> 

In  the  next  example,  the  SHOW  command  is  used  to  find  out  what  other 
users  are  on  the  system  (note  that  the  prompt  shows  the  user  in  user  area  5). 
The  number  of  active  files  in  each  user  area  is  displayed  immediately  below 
the  user  area  number,  and  the  number  of  available  directory  entries  is  dis- 
played at  the  end  of  the  report. 

5A>SHOW  C USERS 3 
Active  User:  5 

Active  Files:  0  1  2  3  4  5  6 
A:  #  o-f  files  82  10  1  2  1  42  12 
A:   Number  o-f  -free  directory  entries:  156 

5A> 

The  following  example  combines  two  options,  SPACE  and  DIR,  to 
determine  the  space  left  on  the  disk  and  in  the  disk's  directory. 

A>SHOW  B: CSPACE  DIRD 
B:    RW,    Space:  1,433k 

B:   Number  o-f  -free  directory  entries:  221 

A> 
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UTILITY  PROGRAMS 

Several  utility  programs  are  provided  with  the  C-128  system.  It  is  important 
to  be  aware  of  these  utilities  and  to  learn  how  to  use  them.  This  is  particularly 
true  of  the  disk-formatting  and  copying  programs. 

FORMAT 

Preparing  a  Disk  for  Use 

Before  any  operation  can  begin,  the  computer  must  know  where  to  put 
information  on  the  disk.  You  may  recall  that  a  disk  is  laid  out  in  sectors  and 
tracks.  How  does  the  computer  distinguish  between  the  sectors  and  tracks  of  a 
disk?  How  does  it  assign  information  within  a  sector  or  track? 

Part  of  this  job  is  done  by  the  hardware  (equipment)  and  CP/M,  but  you 
will  first  have  to  prepare  the  disk.  Every  blank  disk  must  be  formatted  before 
you  can  put  data  onto  it.  This  is  a  good  practice  even  if  your  disk  vendor 
claims  to  have  formatted  your  disks. 

Your  initialization  program  is  called  FORMAT  A  FORMAT  program 
session  might  look  like  this: 

A > FORMAT 

DISK  TO  FORMAT?    <A,B,C,D)  B 
PRESS  RETURN  TO  BEGIN  FORMATTING 
DISK  FORMATTED.      MORE?      (Y/N)  N 
A> 

While  the  exact  syntax  of  the  messages  may  differ,  these  steps  normally 
occur  in  any  format  program: 

1.  Run  the  program  (type  its  name  and  then  press  RETURN). 

2.  Tell  the  program  which  drive  contains  the  disk  to  be  formatted. 

3.  If  your  system  runs  both  single-  and  double-density  disks,  you  must 
specify  a  density. 

4.  Tell  the  program  to  start  formatting. 

5.  Tell  the  program  whether  you  want  to  quit  or  format  another  disk 
when  it  finishes. 

The  program  may  direct  you  to  remove  any  disk  you  are  not  formatting 
so  as  to  prevent  accidental  formatting  of  a  disk  that  contains  valuable, 


420  USER  GUIDE 


irreplaceable  information. 

The  format  program  may  or  may  not  obey  the  write-protect  notch  on  the 
disk.  To  determine  this,  try  to  format  an  expendable  protected  disk.  If  the 
format  program  ignores  the  write-protect  mechanism,  then  you  must  be  extra 
careful  not  to  inadvertently  format  a  disk  containing  useful  information. 

Initializing  a  disk  only  prepares  it  for  use.  If  you  ask  for  a  directory  of  the 
disk  after  initializing  it,  messages  like  NO  FILE  or  NOT  FOUND  appear, 
since  no  files  are  yet  present.  Also,  initializing  a  disk  does  not  mean  that  the 
disk  can  be  used  to  boot  (start)  the  system;  the  disk  does  not  yet  contain  the 
CP/M  system  (see  COPYSYS  given  later). 

The  format  program  moves  the  magnetic  head  of  the  disk  drive  to  the 
first  sector  of  the  first  track.  The  program  then  writes  some  known  dummy 
information  and  moves  on.  Each  sector  of  a  track  is  written  into,  and  the  head 
moves  to  the  next  track.  Most  programs  fill  the  disk  with  the  hexadecimal 
byte  E5.  You  probably  will  not  care  what  is  done,  or  how,  so  long  as  the  disk  is 
properly  formatted. 

Note  that  the  amount  of  time  a  formatting  program  takes  is  directly 
proportional  to  the  storage  capacity  of  the  disk  drive.  Formatting  a  small- 
capacity  disk  may  take  only  30  seconds,  while  formatting  a  hard  disk  drive 
may  require  as  much  as  30  minutes. 

COPYSYS 

Placing  the  CP/M  System  on  Disk 

CP/M-PLUS  program  information  is  stored  as  a  file  on  disk  (named 
CPM3.SYS).  On  the  special  "boot"  tracks  at  the  beginning  of  the  disk,  a 
"loader"  program  is  stored.  The  loader  program's  purpose  is  to  take  control 
of  the  system  when  it  is  started,  load  CPM.SYS  into  the  proper  position  in 
memory,  initialize  some  parameters  CP/M-PLUS  will  be  using,  and  pass 
control  to  CP/M-PLUS. 

The  following  steps  occur  in  the  COPYSYS  program: 

1.  Identification  of  the  program. 

2.  Program  asks  user  for  name  of  disk  that  contains  a  valid  CP/M- 
PLUS  system.  User  responds  with  drive  letter. 

3.  System  prompts  user  to  place  disk  in  drive  and  press  RETURN. 

4.  Program  asks  user  for  name  of  disk  on  which  to  place  copy  of  the 
system.  User  responds  with  drive  letter. 

5.  System  prompts  user  to  place  disk  in  drive  and  press  RETURN. 
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6.  Program  repeats  last  step  until  user  enters  return  instead  of  drive 
letter. 

In  this  most  simple  form,  the  computer/  user  dialog  may  look  something 
like  this: 

A>COPYSYS 

COPYBYS  for  CP/M-PLUS  —  by  Your  Computer  Co. 
Drive  to  get  CP/M— PLUS  -from   (A:-P)?  A: 
Place  disk  with  CP/M— PLUS  on   it   in  drive  A 
and  press  RETURN  when  ready- 
Drive  to  put  CP/M-PLUS  on  <A:-P:>? 
Place  dick  to  receive  CP/M-PLUS  in  drive  B 
and  press  RETURN  when  ready. 

Drive  to  put  CP/M-PLUS  on  (A:-P:)? 
Returning  to  CP/M-PLUS... 

A> 

Error  messages  vary  among  COPYSYS  programs,  but  the  following 
types  of  messages  may  occur: 

FILE  NOT  FOUND: 

The  CPM.SYS  (or  CPM3.SYS)  file  was  not  found  on  the  disk  you 
indicated. 

NO  SPACE:  or  DIRECTORY  FULL: 

There  is  not  enough  room  on  the  disk  you  specified  to  store  the  copy 
of  CP/M-PLUS. 


APPENDIX 


Memory  Usage 


A 


The  main  function  of  any  memory  map  is  to  help  you  utilize  the  many  built-in 
functions  of  your  computer.  The  following  memory  guide  does  not  catalog 
every  memory  location  in  the  C-128  map.  Instead,  it  indicates  those  locations 
that  are  the  most  useable  and  includes  a  detailed  explanation  of  what  each 
location  does  and  how  it  works. 


INTERPRETING  POINTERS 

Many  of  the  memory  locations  included  in  this  guide  are  paired.  Instead  of 
performing  the  indicated  function,  these  locations  point  to  the  location  of  the 
function  listed.  This  allows  you  to  move  certain  functions  around  in  memory. 
For  example,  location  2604  points  to  the  beginning  of  the  screen  memory.  By 
changing  this  number,  you  can  use  different  parts  of  memory  for  the  screen. 
By  doing  this  you  can  set  up  different  screens  and  switch  between  them  by 
changing  the  number  in  this  location. 

In  addition,  some  of  these  locations  keep  track  of  functions  within  the 
computer  such  as  location  144,  which  monitors  the  status  of  the  current  I/O 

423 


424    C-128  USER  GUIDE 

device  logged  onto  the  system.  By  reading  the  value  in  this  location,  you  can 
determine  an  OK  condition  or,  if  necessary,  an  error  condition. 

Those  locations  that  are  organized  as  address  pairs  contain  two  numbers 
that  represent  a  single  hexadecimal  number.  To  convert  these  two  numbers 
into  a  decimal  value  (for  PEEKing  or  POKEing)  use  the  following  formula: 

value  =  lower  memory  location  +  (upper  memory  location  X  256) 

Here  is  a  short  BASIC  routine  that  will  perform  this  function  for  you. 

10  INPUT  "VALUE  IN  LOWER  MEMORY  LOCATION";  L 
20  INPUT  "VALUE  IN  HIGHER  MEMORY  LOCATION";  H 
30  PRINT  "DECIMAL  VALUE  =";  L+256*H 


Memory 
Location 


Function 


45&46 


These  locations  contain  the  address  of  the  first  byte  of  your 
BASIC  program. 


47&48 


These  locations  contain  the  address  of  the  first  byte  of  the 
variables  in  your  BASIC  program. 


49&50 


These  locations  contain  the  address  of  the  beginning  of  the 
BASIC  arrays. 


51  &52 


The  number  stored  in  these  locations  is  one  byte  higher  than 
the  end  of  BASIC  arrays. 


53&54 


The  number  stored  in  these  locations  indicate  the  lowest 
memory  location  used  for  storing  the  strings  in  your  BASIC 
program. 


57&58 


These  two  locations  indicate  the  highest  memory  location 
used  by  BASIC. 


144 


The  I/O  status  byte.  This  location  stores  a  number  which 
indicates  the  conditional  I/O  device  in  operation.  A  zero  in 
this  location  indicates  an  OK  condition.  Table  8-2  (in  Chap- 
ter 8)  gives  the  error  codes  for  any  other  number  in  this 
location. 


160-162 


The  jiffy  clock.  The  number  in  these  three  locations  is  a 
straight  binary  number.  To  interpret  its  value,  use  the  follow- 
ing routine: 
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10  A=PEEK(160) 

20  B*PEEK<161) 

30  C=»PEEKU62) 

40  D=0  ( ( 256 )  *B  )  +  ( 65536* A  ) 

50  PRINT  D 


192  This  is  the  cassette  motor  interlock.  Ordinarily  it  is  used  to 

turn  the  Datassette  ON  and  OFF  during  read  and  write  opera- 
tions. It  can  also  be  used  as  an  I  /  O  line  to  control  other  low 
current  devices.  See  Figure  B-6  for  the  CASSETTE  MOTOR 
line  of  the  cassette  port. 

213  The  value  of  the  current  key  being  pressed  can  be  read  in  this 

location. 

208  This  location  can  be  read  to  determine  how  many  characters 

are  currently  in  the  keyboard  buffer  (there  are  a  maximum  of 
ten).  Any  keystrokes  after  the  tenth  entry  will  be  lost. 

842-851  The  keyboard  buffer. 

2565-2566        These  locations  point  to  the  lowest  memory  location  of  the 
operating  system. 

2567-2568        These  locations  point  to  the  highest  memory  location  of  the 
operating  system. 

2604  This  location  controls  the  location  of  screen  memory  and  the 

location  of  the  character  set. 

2592  This  location  controls  the  size  of  the  keyboard  buffer.  By 

changing  this  value  (which  is  initialized  to  ten  whenever  the 
system  is  reset)  you  can  control  the  number  of  keystrokes  that 
will  be  stored  while  the  computer  is  operating. 

2594  Repeat  key  ON/ OFF.  on  =  128,  OFF  =  0 

2595  Repeat  rate.  This  location  controls  the  speed  of  the  repeat 
function. 

2596  Repeat  delay.  This  location  determines  how  long  a  key  must 
be  depressed  before  it  will  begin  repeating. 

1024-2023        Location  of  Screen  Memory  at  power  up. 

2040-2047        These  locations  control  the  locations  of  the  sprites  in 
memory. 
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53248-54271 

53248 
53249 
53250 
53251 
53252 
53253 
53254 
53255 
53256 
53257 
53258 
53259 
53260 
53261 
53262 
53263 
53264 

53265 


53266 
53267 
53268 
53269 


VIC  II  Chip  Control  Registers 

Sprite  #0:  X  position 

Sprite  #0:  Y  position 

Sprite  #1:  X  position 

Sprite  #1:  Y  position 

Sprite  #2:  X  position 

Sprite  #2:  Y  position 

Sprite  #3:  X  position 

Sprite  #3:  Y  position 

Sprite  #4:  X  position 

Sprite  #4:  X  position 

Sprite  #5:  X  position 

Sprite  #5:  Y  position 

Sprite  #6:  X  position 

Sprite  #6:  X  position 

Sprite  #7:  X  position 

Sprite  #7:  Y  position 
Sprites  0-7  MSB  of  X  position 

VIC  II  Chip  Control  Register 

Bits  0-2:  Smooth  Scroll  (Y  direction) 
Bit  3:  24/25  Row  Select  (24=0) 
Bit  4:  Screen  Blanking  (Blank=0) 
Bit  5:  Enable  Bit  Map  Mode  (l=ON) 
Bit  6:  Extended  Color  Text  (l=ON) 
Bit  7:  Raster  Value  Register  (MSB) 

Raster  Value  Register  (Bits  0-7) 

Light  Pen  (X  Value) 

Light  Pen  (Y  Value) 

Sprite  Display  Control  Register 


Bit  0: 

Sprite  #0 

(1 

=ON) 

Bit  1: 

Sprite  #1 

(1 

=ON) 

Bit  2: 

Sprite  #2 

(1 

=ON) 

Bit  3: 

Sprite  #3 

(1 

=ON) 

Bit  4: 

Sprite  #4 

(1 

=ON) 

Bit  5: 

Sprite  #5 

(1 

=ON) 

Bit  6: 

Sprite  #6 

(1 

=ON) 

Bit  7: 

Sprite  #7 

(1 

=ON) 

53270 


VIC  II  Control  Register  #2 

Bits  0-2:  Smooth  Scroll  (X  direction) 
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Bit  3:  38/40  Column  Select  (1=40) 
Bit  4:  Multicolor  Mode  (l=ON) 
Bits  5-7:  Not  used 

53271  Sprite  Expansion  Register  (Y  direction) 


Bit  0: 

Sprite  #0(P 

=2X) 

Bit  1: 

Sprite  #1  (1= 

=2X) 

Bit  2: 

Sprite  #2  (1: 

=2X) 

Bit  3: 

Sprite  #3  (1= 

=2X) 

Bit  4: 

Sprite  #4(1= 

=2X) 

Bit  5: 

Sprite  #5  (1= 

=2X) 

Bit  6: 

Sprite  #6(1: 

=2X) 

Bit  7: 

Sprite  #7(1: 

=2X) 

VIC  II  Address  Control  Register 

Bit  0: 

Not  used 

Bits  1-3:  Character  Set  Location 
Bits  4-7:  Screen  Location 

53273  VIC  II  Interrupt  Control  Register 

Bit  0:  Raster  Compare 

Bit  1:  Sprite-Background  Collision 

Bit  2:  Sprite-Sprite  Collision 

Bit  3:  Light  Pen  Interrupt 

Bits  4-6:  Not  used 

53274  VIC  II  Interrupt  Enable  Register 

Bit  0:  Raster  Compare  (l=ON) 

Bit  1:  Sprite-Background  Collision  (l=ON) 

Bit  2:  Sprite-Sprite  Collision  (l=ON) 

Bit  3:  Light  Pen  Interrupt  (l=ON) 

Bits  4-6:  Not  Used  (l=ON) 

53275  Sprite-Background  Priority  Register 

BitO:  Sprite  #0  (1=SPRITE) 
Bit  1:  Sprite  #1  (1=SPRITE) 
Bit  2:  Sprite  #2  (1=SPRITE) 
Bit  3:  Sprite  #3  (1=SPRITE) 
Bit  4:  Sprite  #4  (1=SPRITE) 
Bit  5:  Sprite  #5  (1=SPRITE) 
Bit  6:  Sprite  #6  (1=SPRITE) 
Bit  7:  Sprite  #7  (1=SPRITE) 

53276  Sprite  Multicolor  Control  Register 

Bit  0:  Sprite  #0  (1= Multicolor) 
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Bit  1:  Sprite  #1  (1= Multicolor) 

Bit  2:  Sprite  #2  (1= Multicolor) 

Bit  3:  Sprite  #3  (1= Multicolor) 

Bit  4:  Sprite  #4  (1= Multicolor) 

Bit  5:  Sprite  #5  (1= Multicolor) 

Bit  6:  Sprite  #6  (1= Multicolor) 

Bit  7:  Sprite  #7  (1= Multicolor) 

53277  Sprite  Expansion  Register  (X  direction) 

BitO:  Sprite  #0(1=2X) 
Bit  1:  Sprite  #1  (1=2X) 
Bit  2:  Sprite  #2  (1=2X) 
Bit  3:  Sprite  #3  (1=2X) 
Bit  4:  Sprite  #4  (1=2X) 
Bit  5:  Sprite  #5  (1=2X) 
Bit  6:  Sprite  #6  (1=2X) 
Bit  7:  Sprite  #7  (1=2X) 

53278  Sprite-Sprite  Collision  Register 

Bit  0:  Sprite  #0  (l=Collision  Detect) 

Bit  1:  Sprite  #1  (l=Collision  Detect) 

Bit  2:  Sprite  #2  (l=Collision  Detect) 

Bit  3:  Sprite  #3  (l=Collision  Detect) 

Bit  4:  Sprite  #4  (l=Collision  Detect) 

Bit  5:  Sprite  #5  (l=Collision  Detect) 

Bit  6:  Sprite  #6  (l=Collision  Detect) 

Bit  7:  Sprite  #7  (l=Collision  Detect) 

53279  Sprite-Background  Collision  Register 

Bit  0:  Sprite  #0  (l=Collision  Detect) 

Bit  1:  Sprite  #1  (1= Collision  Detect) 

Bit  2:  Sprite  #2  (l=Collision  Detect) 

Bit  3:  Sprite  #3  (l=Collision  Detect) 

Bit  4:  Sprite  #4  (l=Collision  Detect) 

Bit  5:  Sprite  #5  (l=Collision  Detect) 

Bit  6:  Sprite  #6  (l=Collision  Detect) 

Bit  7:  Sprite  #7  (l=Collision  Detect) 

53280  Screen  Border  Color 

0  =  BLACK 

1  =  WHITE 
2=  RED 

3  =  CYAN 

4  =  PURPLE 
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5 

= 

GREEN 

6 

= 

BLUE 

7 

= 

YELLOW 

8 

= 

ORANGE 

9 

= 

BROWN 

10 

LIGHT  RED 

11 

DARK  GRAY 

12 

MEDIUM  GRAY 

13 

LIGHT  GREEN 

14 

LIGHT  BLUE 

15 

LIGHT  GRAY 

53281  Background  Color  #  1 


53282 


0  = 

BLACK 

1  - 

WHITE 

2  = 

RED 

3  = 

CYAN 

4  = 

PURPLE 

5  = 

GREEN 

6  = 

BLUE 

7  = 

YELLOW 

8  = 

ORANGE 

9  = 

BROWN 

10  = 

LIGHT  RED 

11  = 

DARK  GRAY 

12  = 

MEDIUM  GRAY 

13  = 

LIGHT  GREEN 

14  = 

LIGHT  BLUE 

15  = 

LIGHT  GRAY 

cground  Color  #2 

0  = 

BLACK 

1  = 

WHITE 

2  = 

RED 

3  = 

CYAN 

4  = 

PURPLE 

5  = 

GREEN 

6  = 

BLUE 

7  = 

YELLOW 

8  = 

ORANGE 

9  = 

BROWN 

10  = 

LIGHT  RED 

1 1=  DARK  GRAY 
12  =  MEDIUM  GRAY 
13=  LIGHT  GREEN 
14=  LIGHT  BLUE 
15=  LIGHT  GRAY 

Background  Color  #2 


0  = 

BLACK 

1  = 

WHITE 

2  = 

RED 

3  = 

CYAN 

4  = 

PURPLE 

5  = 

GREEN 

6  = 

BLUE 

7  = 

YELLOW 

8  = 

ORANGE 

9  = 

BROWN 

10  = 

LIGHT  RED 

11  = 

DARK  GRAY 

12  = 

MEDIUM  GRAY 

13  = 

LIGHT  GREEN 

14  = 

LIGHT  BLUE 

15  = 

LIGHT  GRAY 

kground  Color  #3 

0  = 

BLACK 

1  = 

WHITE 

2  = 

RED 

3  = 

CYAN 

4  = 

PURPLE 

5  = 

GREEN 

6  = 

BLUE 

7  = 

YELLOW 

8  = 

ORANGE 

9  = 

BROWN 

10  = 

LIGHT  RED 

11  = 

DARK  GRAY 

12  = 

MEDIUM  GRAY 

13  = 

LIGHT  GREEN 

14  = 

LIGHT  BLUE 

15  = 

LIGHT  GRAY 
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53285 
53286 

53287-53294 


54727-55295 

54272-54278 

54272 

54273 

54274 

54275 

54276 


54277 


Sprite  Multicolor  Register  #0 
Sprite  Multicolor  Register  #l 
Sprite  Color  Registers  0-7 


0 

- 

m  \c  k 

l 

= 

WHITE 

2 

= 

RED 

3 

CYAN 

4 

PURPLE 

5 

GREEN 

6 

BLUE 

7 

YELLOW 

8 

ORANGE 

9 

BROWN 

10 

LIGHT  RED 

ll 

DARK  GRAY 

12 

MEDIUM  GRAY 

13 

LIGHT  GREEN 

14 

LIGHT  BLUE 

15 

LIGHT  GRAY 

SID  Chip  Control  Registers 

Sound  Register  #1 

Frequency  Control  (Low  Byte) 

Frequency  Control  (High  Byte) 

Pulse  Width  Value  (Low  Byte) 

Pulse  Width  Value  (High  Byte) 

Sound  Control  Register 

BitO:  Sound  ON/ OFF  (l=ON) 

Bit  1:  Sync  Bit  (l=ON) 

Bit  2:  Ring  Modulation  (l=ON) 

Bit  3:  Test  Bit  (Normally  not  used) 

Bit  4:  Triangle  Wave  (l=ON) 

Bit  5:  Sawtooth  Waveform  (l=ON) 

Bit  6:  Square  Wave  (l=ON) 

Bit  7:  White  Noise  (l=ON) 

Attack/ Decay  Control  Register 
Bits  0-3:  Decay  Value 
Bits  4-7:  Attack  Value 
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54278  Sustain/ Release  Control  Register 

Bits  0-3:  Release  Value 

54279-54285  Sound  Register  #2 

54279  Frequency  Control  (Low  Byte) 

54280  Frequency  Control  (High  Byte) 

54281  Pulse  Width  Value  (Low  Byte) 

54282  Pulse  Width  Value  (High  Byte) 

54283  Sound  Control  Register 

BitO:  Sound  ON/ OFF  (1= ON) 

Bit  1:  SYNC  Bit  (l=ON) 

Bit  2:  Ring  Modulation  (l=ON) 

Bit  3:  Test  Bit  (Normally  not  used) 

Bit  4:  Triangle  Wave  (l=ON) 

Bit  5:  Sawtooth  Waveform  (l=ON) 

Bit  6:  Square  Wave  (1= ON) 

Bit  7:  White  Noise  (1= ON) 

54284  Attack/  Decay  Control  Register 

Bits  0-3:  Decay  Value 
Bits  4-7:  Attack  Value 

54285  Sustain/ Release  Control  Register 

Bits  0-3:  Release  Value 
Bits  4-7:  Sustain  Value 

54286-54292  Sound  Register  #3 

54286  Frequency  Control  (Low  Byte) 

54287  Frequency  Control  (High  Byte) 

54288  Pulse  Width  Value  (Low  Byte) 

54289  Pulse  Width  Value  (High  Byte) 

54290  Sound  Control  Register 

Bit  0:  Sound  ON /OFF  (l=ON) 

Bit  1:  Sync  Bit  (l=ON) 

Bit  2:  Ring  Modulation  (l=ON) 

Bit  3:  Test  Bit  (Normally  not  used) 

Bit  4:  Triangle  Wave  (l=ON) 

Bit  5:  Sawtooth  Waveform  (l=ON) 

Bit  6:  Square  Wave  (l=ON) 

Bit  7:  White  Noise  (l=ON) 


Attack/  Decay  Control  Register 
Bits  0-3:  Decay  Value 
Bits  4-7:  Attack  Value 

Sustain/  Release  Control  Register 
Bits  0-3:  Release  Value 
Bits  4-7:  Sustain  Value 

Sound  Filter  Functions 

Filter  Cutoff  Value  (Low  Byte) 

Filter  Cutoff  Value  (High  Byte) 

Filter/ Resonance  Control  Register 

Bit  0:  Sound  Register  #1  Filter  (l=ON) 
Bit  1:  Sound  Register  #2  Filter  (l=ON) 
Bit  2:  Sound  Register  #3  Filter  (l=ON) 
Bit  3:  External  Filter  (l=ON) 
Bits  4-7:  Resonance  Value 
Bits  4-7:  Sustain  Value 

Mode/ Volume  Control 

Bits  0-3:  Volume  Control  Register 

Bit  4:  Low  Pass  Filter 

Bit  5:  Band  Pass  Filter 

Bit  6:  High  Pass  Filter 

Bit  7:  Sound  Register  #3  ON/ OFF  (l=OFF) 

Paddle  Controller  X-value 

Paddle  Controller  Y-value 

Oscillator  #3  Random  Number  Generator 

Envelope  Register 

CIA  (Complex  Interface  Adapter)  #1 

Port  A 

Bits  0-7:  Keyboard  Column  Key  Values 
Bits  0-3:  (alt)  Direction  (Joystick  A) 
Bits  2&3:  (alt)  Paddle  Fire  Buttons 
Bit  4:  (alt)  Fire  Button  (Joystick  A) 
Bit  6&7:  (alt)  Port  A  Paddle  Values 

Port  B 

Bits  0-7:  Keyboard  Row  Key  Values 
Bits  0-3:  (alt)  Direction  (Joystick  B) 
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56322 
56323 

56324-56327 

56324 

56325 

56326 

56327 

56328-56331 

56328 

56329 

56330 

56331 

56332 
56333 


56334 


56335 


Bits  2&3:  (alt)  Paddle  Fire  Buttons 
Bit  4:  (alt)  Fire  Button  (Joystick  B) 
Bit  6&7:  (alt)  Port  B  Paddle  Values 

Port  A  Input/ Output  Direction  Register 

Port  B  Input/ Output  Direction  Register 

Timers 

Timer  A  (Low  Byte) 

Timer  A  (High  Byte) 

Timer  B  (Low  Byte) 

Timer  B  (High  Byte) 
Real  Time  Clock 

0.1  Seconds 

Seconds 

Minutes 

Bits  0-6:  Hours 

Bit  7:  AM/PM  Indicator 

Serial  1/ O  Buffer  (Synchronous) 

Interrupt  Control  Register 
BitO:  Timer  A 
Bit  1:  Timer  B 
Bit  2:  Clock  Alarm 
Bit  3:  Serial  Port 

Bit  4:  Cassette  Read/ Serial  Bus  SRQ  Input 
Bit  7:  Interrupt  Detect  Bit 

Control  Register  A 

Bit  0:  Start/Stop  Timer  (l=Start) 

Bit  1:  Timer  Output  (l=ON) 

Bit  2:  Timer  Mode  (l=Toggle,  0=Pulse) 

Bit  3:  Timer  Run  Mode  (l=One  Shot,  0=Cont) 

Bit  4:  Preset  Timer  (l=Preset) 

Bit  5:  Timer  Clock  Source  (l=Int,  0=  System) 

Bit  6:  Serial  Port  I/O  Mode  (1= Output) 

Bit  7:  Real  Time  Clock  Freq  (0=60  Hz) 

Control  Register  B 

BitO:  Start/ Stop  Timer  (1= Start) 
Bit  1:  Timer  Output  (l=ON) 
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Bit  2:  Timer  Mode  (l=Toggle,  0=Pulse) 

Bit  3:  Timer  Run  Mode  (l=One  Shot,  0=Cont) 

Bit  4:  Preset  Timer  (1= Preset) 

Bits  5&6:  Timer  B  Mode  Select 

0  =  Clock  Source:  System 

1  =  Clock  On  Positive  Pulses 

2  =  Carry  From  Timer  A 

3  =  Carry  From  Timer  A  Positive  Pulses 
Bit  7:  Set  Alarm  (l=Set) 

2  =  Carry  From  Timer  A 

3  =  Carry  From  Timer  A  Positive  Pulses 
Bit  7:  Set  Alarm  (l=Set) 

56576-56831     CIA  (Complex  Interface  Adapter)  #2 

56576  Data  Port  A 

Bits  0&1:  VIC  II  Chip  Bank  Select 

0  =  Bank  3  (49152-65535) 

1  =  Bank  2  (32768-49151) 
2=  Bank  1  (16384-32767) 
3  =  Bank  0  (00000-16383) 

Bit  2:  RS-232  User  Data  Output 

Bit  3:  ATN  Output  Signal 

Bit  4:  Serial  Bus  Output  Clock  Pulse 

Bit  5:  Serial  Bus  Output 

Bit  6:  Serial  Bus  Input  Clock  Pulse 

Bit  7:  Serial  Bus  Input 

56577  Data  Port  B  (RS-232  User  Port) 

Bit  0:  Data  Received 

Bit  1 :  Request  to  Send 

Bit  2:  Data  Terminal  Ready 

Bit  3:  Ring  Indicator 

Bit  4:  Carrier  Detect 

Bit  6:  Clear  to  Send 

Bit  7:  Data  Set  Ready 

56578  Port  A  Input/ Output  Direction  Register 

56579  Port  B  Input/ Output  Direction  Register 

56580  Timers 

56580  Timer  A  (Low  Byte) 

56581  Timer  A  (High  Byte) 
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56582  Timer  B  (Low  Byte) 

56583  Timer  B  (High  Byte) 
56584-56587  Real  Time  Clock 

56584  0.1  Seconds 

56585  Seconds 

56586  Minutes 

56587  Bits  0-6:  Hours 

Bit  7:  AM/PM  Indicator 

6588  Serial  I  /  O  Buffer  (Synchronous) 

56589  Interrupt  Control  Register 

Bit  0:  Timer  A 

Bit  1:  Timer  B 

Bit  2:  Clock  Alarm 

Bit  3:  Serial  Port 

Bit  4:  Cassette  Read/ Serial  Bus  SRQ  Input 

Bit  7:  Interrupt  Detect  Bit 

56590  Control  Register  A 

BitO:  Start/ Stop  Timer  (1= Start) 

Bit  1:  Timer  Output  (l=ON) 

Bit  2:  Timer  Mode  (l=Toggle,  0=Pulse) 

Bit  3:  Timer  Run  Mode  (l=One  Shot,  0=Cont) 

Bit  4:  Preset  Timer  (l=Preset) 

Bit  5:  Timer  Clock  Source  (l=lnt,  0=System) 

Bit  6:  Serial  Port  I/O  Mode  (l=Output) 

Bit  7:  Real  Time  Clock  Freq  (0=60Hz) 

56591  Control  Register  B 

Bit  O:  Start/ Stop  Timer  (1= Start) 

Bit  1:  Timer  Output  (l=ON) 

Bit  2:  Timer  Mode  (l=Toggle,  0=  Pulse) 

Bit  3:  Timer  Run  Mode  (l=One  Shot,  0=Cont) 

Bit  4:  Preset  Timer  (1= Preset) 

Bits  5&6:  Timer  B  Mode  Select 

0  =  Clock  Source:  System 

1  =  Clock  On  Positive  Pulses 

2  =  Carry  From  Timer  A 

3  =  Carry  From  Timer  A  Positive  Pulses 
Bit  7:  Set  Alarm  (l=Set) 
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 APPENDIX 

C-128  I/O  PINOUTS 


This  section  contains  the  pinouts  of  all  the  I/O  connectors  on  the  C-128. 
Using  this  information,  you  can  design  your  own  interfaces  for  devices  that  do 
not  hook  up  directly  to  the  C-128. 


Control  Port  1 
1     2     3     4  5 

O  O  O  O  O 


o       o       o  o 

6     7     8  9 
Control  Port  2 
1     2     3     4  5 

o       o       o       o  o 


o       o       o  o 

6     7     8  9 


Pin  No. 

Type 

1 

JOYO 

2 

JOY1 

3 

JOY2 

4 

JOY3 

5 

POT  Y 

6 

Fire  Button 

7 

+5  V  (50  mA  max) 

8 

GND 

9 

POT  X 

FIGURE  EM.  Game  port  pinout 
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1    2    3    4    5   6    7    8    9  10  11  12  13  14  15  16  17  18  19  20  21  22 


ABCDEFHJ    KLMNP  RSTUVWXYZ 


Pin  No. 

Type 

Pin  No. 

Type 

1 

GND 

12 

BA 

2 

+  5  V 

13 

DMA 

3 

+5  V 

14 

D7 

4 

IRQ 

15 

D6 

5 

R/W 

16 

D5 

6 

DOT  CLOCK 

17 

D4 

7 

I/O  1 

18 

D3 

8 

GAME 

19 

D2 

9 

EX  ROM 

20 

Dl 

10 

I/O  2 

21 

DO 

11 

ROM  L 

22 

GND 

Pin  No. 

Type 

A 

GND 

B 

ROM  H 

C 

RESET 

D 

NMI 

E 

S  02 

F 

A  15 

H 

A  14 

J 

A  13 

K 

A  12 

L 

A  11 

M 

A  10 

Pin  No. 

Type 

N 

A9 

P 

A8 

R 

A7 

S 

A6 

T 

A5 

U 

A4 

V 

A3 

w 

A2 

X 

Al 

Y 

AO 

Z 

GND 

FIGURE  B-2.  Expansion  port  pinout 
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FIGURE  B-4.  Serial  I/O  port  pinout 
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1  2     3     4      5     6      7     8     9     10  11  12 


A         BCDEFHJKL  MN 


T>in  M r» 

rlu  lvo. 

lype 

1 

GND 

2 

+5  V 

3 

RESET 

4 

CONTROL  1 

5 

SP  1 

6 

CONTROL  2 

7 

SP  2 

o 
O 

PC  2 

9 

SERIAL  ATN  IN 

10 

+9  V  (100  m A  max) 

11 

+9  V  (100  mA  max) 

12 

GND 

A 

GND 

B 

FLAG  2 

C 

PB0 

D 

PB1 

E 

PB2 

F 

PB3 

H 

PB4 

J 

PB5 

K 

PB6 

L 

PB7 

M 

PA2 

N 

GND 

FIGURE  B-5.  User  port  pinout 
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Pin  No. 

Type 

A  and  l 

GND 

B  and  2 

+5  V 

Cand3 

CASSETTE  MOTOR 

D  and  4 

CASSETTE  READ 

E  and  5 

CASSETTE  WRITE 

F  and  6 

CASSETTE 

FIGURE  B-6.  Cassette  interface  pinout 


3  4 


6     7  8 


Pin  No. 

Type 

I 

GND 

2 

GND 

3 

RED 

4 

GREEN 

5 

BLUE 

6 

INTENSITY 

7 

MONOCHROME 

8 

HORIZ.  SYNC 

9 

VERT  SYNC 

FIGURE  B-7.  RGB  1  Connection 
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Conversion  Tables  — 
Trigonometric  Functions  \j 


The  tables  in  this  section  are  intended  as  an  aid  to  mathematical  programming. 

Hexadecimal-Decimal  Integer  Conversion 

Table  C-l  provides  for  direct  conversions  between  hexadecimal  integers  in 
the  range  0-FFF  and  decimal  integers  in  the  range  0-4095.  For  conversion  of 
larger  integers,  the  table  values  may  be  added  to  the  figures  in  Table  C-2. 
Hexadecimal  fractions  may  be  converted  to  decimal  fractions  as  follows: 

1 .  Express  the  hexadecimal  fraction  as  an  integer  times  16—/?,  where  n  is 
the  number  of  significant  hexadecimal  places  to  the  right  of  the 
hexadecimal  point. 

O.CA9BF316=  CA9  BF316  X  16~6 

2.  Find  the  decimal  equivalent  of  the  hexadecimal  integer. 

CA9  BF31fi  =  13  278  195in 
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TABLE  C-1.  Hexadecimal-Decimal  Integer  Conversion 


0 

1 

2 

3 

4 

5 

6 

7 

8 

9 

A 

B 

C 

D 

E 

F 

00 

0000 

0001 

0002 

0003 

0004 

0005 

0006 

0007 

0008 

0009 

0010 

0011 

0012 

0013 

0014 

0015 

01 

0016 

0017 

0018 

0019 

0020 

0021 

0022 

0023 

0024 

0025 

0026 

0027 

0028 

0029 

0030 

0031 

02 

0032 

0033 

0034 

0035 

0036 

0037 

0038 

0039 

0040 

0041 

0042 

0043 

0044 

0045 

0046 

0047 

03 

0048 

0049 

0050 

0051 

0052 

0053 

0054 

0055 

0056 

0057 

0058 

0059 

0060 

0061 

0062 

0063 

04 

0064 

0065 

0066 

0067 

0068 

0069 

0070 

0071 

0072 

0073 

0074 

0075 

0076 

0077 

0078 

0079 

05 

0080 

0081 

0082 

0083 

0084 

0085 

0086 

0087 

0088 

0089 

0090 

0091 

0092 

0093 

0094 

0095 

06 

0096 

0097 

0098 

0099 

0100 

0101 

0102 

0103 

0104 

0105 

0106 

0107 

0108 

0109 

01  10 

01  1  1 

07 

0112 

0113 

0114 

0115 

0116 

0117 

0118 

0119 

0120 

0121 

0122 

0123 

0124 

0125 

0126 

0127 

08 

0128 

0129 

0130 

0131 

0132 

0133 

0134 

0135 

0136 

0137 

0138 

0139 

0140 

0141 

0142 

0143 

09 

0144 

0145 

0146 

0147 

0148 

0149 

0150 

0151 

0152 

0153 

0154 

0155 

0156 

0157 

0158 

0159 

OA 

0160 

0161 

0162 

0163 

0164 

0165 

0166 

0167 

0168 

0169 

0170 

0171 

0172 

0173 

0174 

0175 

OB 

0181 

01 82 

01 83 

01 85 

0 1 86 

0 1 87 

oc 

0192 

0193 

0194 

0195 

0196 

0197 

0198 

0199 

0200 

0201 

0202 

0203 

0204 

0205 

0206 

0207 

OD 

0208 

0209 

0210 

0211 

0212 

0213 

0214 

0215 

0216 

0217 

0218 

0219 

0220 

0221 

0222 

0223 

OE 

0224 

0225 

0226 

0227 

0228 

0229 

0230 

0231 

0232 

0233 

0234 

0235 

0236 

0237 

0238 

0239 

OF 

0240 

024 1 

0242 

0243 

0244 

0245 

0246 

0247 

0248 

0249 

0250 

0251 

0252 

0253 

0254 

0255 

10 

0256 

0257 

0258 

0259 

0260 

0261 

0262 

0263 

0264 

0265 

0266 

0267 

0268 

0269 

0270 

0271 

l  l 

0272 

0273 

0274 

0275 

0276 

0277 

0278 

0279 

0280 

0281 

0282 

0283 

0284 

0285 

0286 

0287 

l  2 

0283 

0289 

0290 

0291 

0292 

0293 

0294 

0295 

0296 

0297 

0298 

0299 

0300 

0301 

0302 

0303 

13 

0304 

0305 

0306 

0307 

0308 

0309 

0310 

031 1 

0312 

0313 

0314 

0315 

0316 

0317 

0318 

0319 

14 

0320 

0321 

0322 

0323 

0324 

0325 

0326 

0327 

0328 

0329 

0330 

0331 

0332 

0333 

0334 

0335 

15 

0336 

0337 

0338 

0339 

0340 

0341 

0342 

0343 

0344 

0345 

0346 

0347 

0348 

0349 

0350 

0351 

16 

0352 

0353 

0354 

0355 

0356 

0357 

0358 

0359 

0360 

0361 

0362 

0363 

0364 

0365 

0366 

0367 

17 

0368 

0369 

0370 

0371 

0372 

0373 

0374 

0375 

0376 

0377 

0378 

0379 

0380 

0381 

0382 

0383 

18 

0384 

0385 

0386 

0387 

0388 

0389 

0390 

0391 

0392 

0393 

0394 

0395 

0396 

0397 

0398 

0399 

1  9 

0400 

0401 

0402 

0403 

0404 

0405 

0406 

0407 

0408 

0409 

0410 

04 1  1 

04 1 2 

041 3 

0414 

04 15 

1A 

0416 

0417 

0418 

0419 

0420 

0421 

0422 

0423 

0424 

0425 

0426 

0427 

0428 

0429 

0430 

0431 

IB 

0432 

0433 

0434 

0435 

0436 

0437 

0438 

0439 

0440 

0441 

0442 

0443 

0444 

0445 

0446 

0447 

1 C 

0448 

0449 

0450 

045 1 

0452 

0453 

0454 

0455 

0456 

0457 

0458 

0459 

0460 

046 1 

0462 

0463 

1  D 

0464 

0465 

0466 

0467 

0468 

0469 

0470 

047 1 

0472 

0473 

0474 

0475 

0476 

0477 

0478 

0479 

IE 

0480 

0481 

0482 

0483 

0484 

0485 

0486 

0487 

0488 

0489 

0490 

0491 

0492 

0493 

0494 

0495 

IF 

0496 

0497 

0498 

0499 

0500 

0501 

0502 

0503 

0504 

0505 

0506 

0507 

0508 

0509 

0510 

051  1 

20 

0512 

0513 

0514 

0515 

0516 

0517 

0518 

0519 

0520 

0521 

0522 

0523 

0524 

0525 

0526 

0527 

21 

0528 

0529 

0530 

0531 

0532 

0533 

0534 

0535 

0536 

0537 

0538 

0539 

0540 

0541 

0542 

0543 

22 

0544 

0545 

0546 

0547 

0548 

0549 

0550 

055 1 

0552 

0553 

0554 

0555 

0556 

0557 

0558 

0559 

23 

0560 

0561 

0562 

0563 

0564 

0565 

0566 

0567 

0568 

0569 

0570 

0571 

0572 

0573 

0574 

0575 

24 

0576 

0577 

0578 

0579 

0580 

0581 

0582 

0583 

0584 

0585 

0586 

0587 

0588 

0589 

0590 

0591 

25 

0592 

0593 

0594 

0595 

0596 

0597 

0598 

0599 

0600 

0601 

0602 

0603 

0604 

0605 

0606 

0607 

26 

0608 

0609 

0610 

0611 

0612 

0613 

0614 

0615 

rv>16 

0617 

0618 

0619 

0620 

0621 

0622 

0623 

27 

0624 

0625 

0626 

0627 

0628 

0629 

0630 

0631 

0632 

0633 

0634 

0635 

Q636 

0637 

0638 

0639 

28 

0640 

0641 

0642 

0643 

0644 

0645 

0646 

0647 

0648 

0649 

0650 

0651 

0652 

0653 

0654 

0655 

29 

0656 

0657 

0658 

0659 

0660 

0661 

0662 

0663 

0664 

0665 

0666 

0667 

0668 

0669 

0670 

0671 

2A 

0672 

0673 

0674 

0675 

0676 

0677 

0678 

0679 

0680 

0681 

0682 

0683 

0684 

0685 

0686 

0687 

2B 

0688 

0689 

0690 

0691 

0692 

0693 

0694 

0695 

0696 

0697 

0698 

0699 

0700 

0701 

0702 

0703 

2C 

0704 

0705 

0706 

0707 

0708 

0709 

0710 

0711 

0712 

0713 

0714 

0715 

0716 

0717 

0718 

0719 

2D 

0720 

0721 

0722 

0723 

0724 

0725 

0726 

0727 

0728 

0729 

0730 

0731 

0732 

0733 

0734 

0735 

2E 

0736 

0737 

0738 

0739 

0740 

0741 

0742 

0743 

0744# 

0745 

0746 

0747 

0748 

0749 

0750 

0751 

2F 

0752 

0753 

0754 

0755 

0756 

0757 

0758 

0759 

0760 

0761 

0762 

0763 

0764 

0765 

0766 

0767 
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TABLE  C-1-  Hexadecimal-Decimal  Integer  Conversion  (continued) 


0 

1 

2 

3 

4 

5 

6 

7 

8 

9 

A 

B 

C 

D 

E 

F 

30 

0768 

0769 

0770 

0771 

0772 

0773 

0774 

0775 

0776 

0777 

0778 

0779 

0780 

0781 

0782 

0783 

31 

0784 

0785 

0786 

0787 

0788 

0789 

0790 

0791 

0792 

0793 

0794 

0795 

0796 

0797 

0798 

0799 

32 

0800 

0801 

0802 

0803 

0804 

0805 

0806 

0807 

0808 

0809 

0810 

081  1 

0812 

0813 

0814 

0815 

33 

0816 

0817 

0818 

0819 

0820 

0821 

0822 

0823 

0824 

0825 

0826 

0827 

0828 

0829 

0830 

0831 

34 

0832 

0833 

0834 

0835 

0836 

0837 

0838 

0839 

0840 

084 1 

0842 

0843 

0844 

0845 

0846 

0847 

35 

0848 

0849 

0850 

0851 

0852 

0853 

0854 

0855 

0856 

0857 

0859 

086 1 

0862 

0863 

36 

0864 

0865 

0866 

0867 

0868 

0869 

0870 

0871 

0872 

0873 

0874 

0875 

0876 

0877 

0878 

0879 

37 

0880 

0881 

0882 

0883 

0884 

0885 

0886 

0887 

0888 

0889 

0890 

0891 

0892 

0893 

0894 

0895 

38 

0896 

0897 

0898 

0899 

0900 

0901 

0902 

0903 

0904 

0905 

0906 

0907 

0908 

0909 

0910 

091 1 

39 

0912 

0913 

0914 

0915 

0916 

0917 

0918 

0919 

0920 

0921 

0922 

0923 

0924 

0925 

0926 

0927 

3A 

0928 

0929 

0930 

0931 

0932 

0933 

0934 

0935 

0936 

0937 

0938 

0939 

0940 

0941 

0942 

0943 

38 

0944 

0945 

0946 

0947 

0948 

0949 

0950 

0951 

0952 

0953 

0954 

0955 

0956 

0957 

0958 

0959 

3C 

0960 

0961 

0962 

0963 

0964 

0965 

0966 

0967 

0968 

0969 

0970 

0971 

0972 

0973 

0974 

0975 

3D 

0976 

0977 

0978 

0979 

0980 

0981 

0982 

0983 

0984 

0985 

0986 

0987 

0988 

0989 

0990 

0991 

3E 

0992 

0993 

0994 

0995 

0996 

0997 

0998 

0999 

1000 

1001 

1002 

1003 

1004 

1005 

1006 

1007 

3F 

1008 

1009 

1010 

1011 

1012 

1013 

1014 

1015 

1016 

1017 

1018 

1019 

1020 

1021 

1022 

1023 

40 

1024 

1025 

1026 

1027 

1028 

1029 

1030 

1031 

1032 

1033 

1 034 

1035 

1036 

1037 

1038 

1039 

41 

1040 

1041 

1042 

1043 

1044 

1045 

1046 

1047 

1048 

1049 

1 050 

1051 

1052 

1053 

1054 

1055 

42 

1056 

1057 

1058 

1059 

1060 

1061 

1062 

1063 

1064 

1065 

1066 

1067 

1068 

1069 

1070 

1071 

43 

1072 

1073 

1074 

1075 

1076 

1077 

1078 

1079 

1080 

1081 

1082 

1083 

1084 

1085 

1086 

1087 

44 

1088 

1089 

1090 

1091 

1092 

1093 

1094 

1095 

1096 

1097 

1098 

1099 

1 100 

1 101 

1 102 

1  103 

45 

1  104 

1 105 

1 106 

1 107 

1  108 

1  109 

1110 

1 1 1  1 

1112 

1113 

1  1  14 

1115 

1  1  16 

1117 

1  1  18 

1119 

46 

1  120 

1121 

1  122 

1 123 

1  124 

1 125 

1  126 

1 127 

1128 

1 129 

1  130 

1131 

1 132 

1  133 

1  134 

1  135 

47 

1 136 

1 1  37 

1 1 38 

1  1 39 

1  140 

1  141 

1  142 

1 143 

1  1  44 

1 1 45 

1  146 

1  147 

1 148 

1  1  49 

1  1 50 

1151 

48 

1 152 

1153 

1 154 

1 155 

1 156 

1 157 

1 158 

1 159 

1  160 

1 161 

1  162 

1 163 

1  164 

1  165 

1  166 

1  167 

49 

1  168 

1 169 

1 170 

1 171 

1  172 

1 173 

1 174 

1 175 

1  176 

1 177 

1  178 

1 179 

1 180 

1  181 

1  182 

1  183 

4A 

1 184 

1 185 

1 186 

1 187 

1  188 

1 189 

1  190 

1 191 

1 192 

1 193 

1  194 

1  195 

1 196 

1 1  97 

1  198 

1  199 

4B 

1200 

1201 

1202 

1203 

1204 

1205 

1206 

1207 

1208 

1209 

1210 

1211 

1212 

1213 

1214 

1215 

4C 

1216 

1217 

1218 

1219 

1220 

1221 

1222 

1223 

1224 

1225 

1226 

1227 

1228 

1229 

1230 

1231 

4C 

1232 

1233 

1234 

1235 

1236 

1237 

1238 

1239 

1240 

1241 

1242 

1243 

1244 

1245 

1246 

1247 

4E 

1248 

1249 

1250 

1  251 

1252 

1253 

1254 

1255 

1256 

1257 

1258 

1259 

1260 

1261 

1262 

1263 

4F 

1264 

1265 

1266 

1267 

1268 

1269 

1270 

1271 

1272 

1273 

1274 

1275 

1276 

1277 

1278 

1279 

50 

1 280 

1281 

1 282 

1 283 

1  284 

1 285 

1286 

1287 

1288 

1 289 

1  290 

1 291 

1  292 

1293 

1  294 

1  295 

51 

1 296 

1 297 

1298 

1 299 

1 300 

1301 

1302 

1303 

1304 

1305 

1  306 

1307 

1 308 

1 309 

1310 

1311 

52 

1312 

1313 

1314 

1315 

1316 

1317 

1318 

1319 

1320 

1321 

1322 

1323 

1324 

1325 

1326 

1327 

53 

1328 

1329 

1330 

1331 

1332 

1333 

1334 

1335 

1336 

1337 

1338 

1339 

1340 

1341 

1342 

1343 

54 

1344 

1345 

1346 

1347 

1348 

1349 

1350 

1351 

1352 

1353 

1354 

1355 

1356 

1357 

1358 

1359 

55 

1360 

1361 

1362 

1363 

1364 

1365 

1366 

1367 

1368 

1369 

1 370 

1371 

1372 

1373 

1374 

1375 

56 

1376 

1377 

1378 

1379 

1380 

1381 

1382 

1383 

1384 

1385 

1386 

1387 

1388 

1389 

1390 

1391 

57 

1392 

1393 

1394 

1395 

1396 

1397 

1398 

1399 

1400 

1401 

1402 

1403 

1404 

1405 

1406 

1407 

58 

1408 

1409 

1410 

1411 

1412 

1413 

1414 

1415 

1416 

1417 

1418 

1419 

1420 

1421 

1422 

1423 

59 

1424 

1425 

1426 

1427 

1428 

1429 

1430 

1431 

1432 

1433 

1434 

1435 

1436 

1437 

1438 

1439 

5A 

1440 

1441 

1442 

1443 

1444 

1445 

1446 

1447 

1448 

1449 

1450 

1451 

1452 

1453 

1454 

1455 

5B 

1456 

1457 

1458 

1459 

1460 

1461 

1462 

1463 

1464 

1465 

1466 

1467 

1468 

1469 

1470 

1471 

5C 

1472 

1473 

1474 

1475 

1476 

1477 

1478 

1479 

1480 

1481 

1482 

1483 

1484 

1485 

1486 

1487 

5D 

1488 

1489 

1490 

1491 

1492 

1493 

1494 

1495 

1496 

1497 

1498 

1499 

1500 

1501 

1502 

1503 

5E 

1504 

1505 

1506 

1507 

1508 

1509 

1510 

1511 

1512 

1513 

1514 

1515 

1516 

1517 

1518 

1519 

5F 

1520 

1521 

1522 

1523 

1524 

1525 

1526 

1527 

1528 

1529 

1530 

1531 

1532 

1533 

1534 

1535 
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TABLE  C-1.  Hexadecimal-Decimal  Integer  Conversion  {continued) 


0 

1 

2 

3 

4 

5 

6 

7 

8 

9 

A 

6 

C 

D 

E 

F 

60 

1536 

1537 

1538 

1539 

1540 

1541 

1542 

1543 

1544 

1545 

1546 

1547 

1548 

1549 

1550 

1551 

61 

1552 

1553 

1554 

1555 

1556 

1557 

1558 

1559 

1560 

1561 

1562 

1563 

1564 

1565 

1566 

1567 

62 

1568 

1569 

1570 

1571 

1572 

1573 

1574 

1575 

1576 

1577 

1578 

1579 

1580 

1581 

1582 

1583 

63 

1 584 

1585 

1586 

1587 

1588 

1589 

1590 

1591 

1 592 

1 593 

1594 

1595 

1596 

1 597 

1 598 

1 599 

64 

1600 

1601 

1602 

1603 

1604 

1605 

1606 

1607 

1608 

1609 

1610 

161 1 

1612 

1613 

1614 

1615 

65 

1616 

1617 

16.18 

1619 

1620 

1621 

1622 

1623 

1624 

1625 

1626 

1627 

1628 

1629 

1630 

1631 

66 

1632 

1633 

1634 

1635 

1636 

1637 

1638 

1639 

1640 

1641 

1642 

1643 

1644 

1645 

1646 

1647 

67 

1648 

1649 

1650 

1651 

1652 

1653 

1654 

1655 

1656 

1657 

1658 

1659 

1660 

1661 

1662 

1663 

68 

1664 

1665 

1666 

1667 

1668 

1669 

1670 

1671 

1672 

1673 

1674 

1675 

1676 

1677 

1678 

1679 

69 

1680 

1681 

1682 

1683 

1684 

1685 

1686 

1687 

1688 

1689 

1690 

1691 

1692 

1693 

1694 

1695 

6A 

1696 

1697 

1698 

1699 

1700 

1701 

1702 

1703 

1704 

1705 

1706 

1707 

1708 

1709 

1710 

171  1 

6B 

1712 

1713 

1714 

1715 

1716 

1717 

1718 

1719 

1720 

1721 

1722 

1723 

1724 

1725 

1726 

1727 

6C 

1728 

1729 

1730 

1731 

1732 

1733 

1734 

1735 

1736 

1737 

1738 

1739 

1740 

1741 

1742 

1743 

6D 

1744 

1745 

1746 

1747 

1748 

1749 

1750 

1751 

1752 

1753 

1754 

1755 

1756 

1  757 

1758 

175  9 

6E 

1760 

1761 

1762 

1763 

1764 

1765 

1766 

1767 

1768 

1769 

1770 

1771 

1772 

1773 

1774 

1775 

6F 

1776 

1777 

1778 

1779 

1780 

1781 

1782 

1783 

1784 

1785 

1786 

1787 

1788 

1789 

1790 

1791 

70 

1792 

1793 

1794 

1795 

1796 

1797 

1798 

1799 

1800 

1801 

1802 

1803 

1804 

1805 

1806 

1807 

71 

1808 

1809 

1810 

181 1 

1812 

1813 

1814 

1815 

1816 

1817 

1818 

1819 

1820 

1821 

1822 

1823 

72 

1824 

1825 

1826 

1827 

1828 

1829 

1830 

1831 

1832 

1833 

1834 

1835 

1836 

1837 

1838 

1839 

73 

1  840 

1841 

1842 

1843 

1844 

1845 

1846 

1847 

1848 

1849 

1850 

1851 

1852 

1853 

1854 

1855 

74 

1856 

1857 

1858 

1859 

1860 

1861 

1862 

1863 

1864 

1865 

1866 

1867 

1868 

1869 

1870 

1871 

75 

1872 

1373 

1874 

1875 

1876 

1877 

1878 

1879 

1880 

1881 

1882 

1883 

1884 

1885 

1886 

1887 

76 

1888 

1889 

1890 

1891 

1892 

1893 

1894 

1895 

1896 

1897 

1898 

1899 

1900 

1901 

1902 

1903 

77 

1904 

1905 

1906 

1907 

1908 

1909 

1910 

191 1 

1912 

1913 

1914 

1915 

1916 

1917 

1918 

1919 

78 

1920 

1921 

1922 

1923 

1924 

1925 

1926 

1927 

1928 

1929 

1930 

1931 

1932 

1933 

1934 

1935 

79 

1936 

1937 

1938 

1939 

1940 

1941 

1942 

1943 

1944 

1945 

1946 

1947 

1948 

1949 

1950 

1951 

7A 

1952 

1953 

1954 

1955 

1956 

1957 

1958 

1959 

1960 

1961 

1962 

1963 

1964 

1965 

1966 

1967 

7B 

1968 

1969 

1970 

1971 

1972 

1973 

1974 

1975 

1976 

1977 

1978 

1979 

1980 

1981 

1982 

1983 

7C 

1984 

1985 

1986 

1987 

1988 

1989 

1990 

1991 

1992 

1993 

1994 

1995 

1996 

1997 

1998 

1999 

7D 

2000 

2001 

2002 

2003 

2004 

2005 

2006 

2007 

2008 

2009 

2010 

201  1 

2012 

2013 

2014 

2015 

7E 

2016 

2017 

2018 

2019 

2020 

2021 

2022 

2023 

2024 

2025 

2026 

2027 

2028 

2029 

2030 

2031 

7F 

2032 

2033 

2034 

2035 

2036 

2037 

2038 

2039 

2040 

2041 

2042 

2043 

2044 

2045 

2046 

2047 

80 

2048 

2049 

2050 

2051 

2052 

2053 

2054 

2055 

2056 

2057 

2058 

2059 

2060 

2061 

2062 

2063 

81 

2064 

2065 

2066 

2067 

2068 

2069 

2070 

2071 

2072 

2073 

2074 

2075 

2076 

2077 

2078 

2079 

82 

2080 

2081 

2082 

2083 

2084 

2085 

2086 

2087 

2088 

2089 

2090 

2091 

2092 

2093 

2094 

2095 

83 

2096 

2097 

2098 

2099 

2100 

2101 

21 02 

21 03 

2104 

2105 

2 106 

2 107 

2108 

2 109 

2110 

2111 

84 

2112 

21 13 

2114 

2115 

21  16 

2117 

2118 

2119 

2120 

2121 

2122 

2123 

2124 

2125 

2126 

2127 

85 

2128 

2129 

2130 

2131 

2132 

2133 

2134 

2135 

2136 

2137 

2138 

2139 

2140 

2141 

2142 

2143 

86 

2144 

2145 

2146 

2147 

2148 

2149 

2150 

2151 

2152 

2153 

2154 

2155 

2156 

2157 

2158 

2159 

87 

2160 

2161 

2162 

2163 

2164 

2165 

2166 

2167 

2168 

2169 

2170 

2171 

2172 

2173 

2174 

2175 

88 

2176 

2177 

2178 

2179 

2180 

2181 

2182 

2183 

2184 

2185 

2186 

2187 

2188 

2189 

2190 

2191 

89 

2192 

2193 

2194 

2195 

2196 

2197 

2198 

2199 

2200 

2201 

2202 

2203 

2204 

2205 

2206 

2207 

8A 

2208 

2209 

2210 

2211 

2212 

2213 

2214 

2215 

2216 

2217 

2218 

2219 

2220 

2221 

2222 

2223 

8B 

2224 

2225 

2226 

2227 

2228 

2229 

2230 

2231 

2232 

2233 

2234 

2235 

2236 

2237 

2238 

2239 

8C 

2240 

2241 

2242 

2243 

2244 

2245 

2246 

2247 

2248 

2249 

2250 

2251 

2252 

2253 

2254 

2255 

8D 

2256 

2257 

2258 

2259 

2260 

2261 

2262 

2263 

2264 

2265 

2266 

2267 

2268 

2269 

2270 

2271 

8E 

2272 

2273 

2274 

2275 

2276 

2277 

2278 

2279 

2280 

2281 

2282 

2283 

2284 

2285 

2286 

2287 

8F 

2288 

2289 

2290 

2291 

2292 

2293 

2294 

2295 

2296 

2297 

2298 

2299 

2300 

2301 

2302 

2303 
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TABLE  C-1.  Hexadecimal-Decimal  Integer  Conversion  {continued) 


o 

1 

2 

3 

4 

5 

5 

7 

g 

9 

A 

B 

c 

D 

E 

90 

2304 

2305 

2306 

2307 

2308 

2309 

2310 

2311 

2312 

2313 

2314 

2315 

2316 

2317 

2318 

2319 

91 

2320 

2321 

2322 

2323 

2324 

2325 

2326 

2327 

2328 

2329 

2330 

2331 

2332 

2333 

2334 

2335 

92 

2336 

2337 

2338 

2339 

2340 

2341 

2342 

2343 

2344 

2345 

2346 

2347 

2348 

2349 

2350 

2351 

93 

2352 

2353 

2354 

2355 

2356 

2357 

2358 

2359 

2360 

2361 

2362 

2363 

2364 

2365 

2366 

2367 

94 

2368 

2369 

2370 

2371 

2372 

2373 

2374 

2375 

2376 

2377 

2378 

2379 

2380 

2381 

2382 

2383 

95 

2384 

2385 

2386 

2387 

2388 

2389 

2390 

2391 

2392 

2393 

2394 

2395 

2396 

2397 

2398 

2399 

96 

2400 

2401 

2402 

2403 

2404 

2405 

2406 

2407 

2408 

2409 

2410 

241 1 

2412 

2413 

2414 

2415 

97 

2416 

2417 

2418 

2419 

2420 

2421 

2422 

2423 

2424 

2425 

2426 

2427 

2428 

2429 

2430 

2431 

98 

2432 

2433 

2434 

2435 

2436 

2437 

2438 

2439 

2440 

2441 

2442 

2443 

2444 

2445 

2446 

2447 

99 

2448 

2449 

2450 

2451 

2452 

2453 

2454 

2455 

2456 

2457 

2458 

2459 

2460 

2461 

2462 

2463 

2464 

2465 

2466 

2467 

2468 

2469 

2470 

247 1 

2472 

2473 

2474 

2475 

2476 

2477 

2478 

9B 

2480 

2481 

2482 

2483 

2484 

2485 

2486 

2487 

2488 

2489 

2490 

2491 

2492 

2493 

2494 

2495 

9C 

2496 

2497 

2498 

2499 

2500 

2501 

2502 

2503 

2504 

2505 

2506 

2507 

2508 

2509 

2510 

251  1 

9D 

2512 

2513 

2514 

2515 

2516 

2517 

2518 

2519 

2520 

2521 

2522 

2523 

2524 

2525 

2526 

2527 

9E 

2528 

2529 

2530 

253 1 

2532 

2533 

2534 

2535 

2536 

25  37 

2540 

2542 

9F 

2544 

2545 

2546 

2547 

2548 

2549 

2550 

2551 

2552 

2553 

2554 

2555 

2556 

2557 

2558 

2559 

AO 

2560 

2561 

2562 

2563 

2564 

2565 

2566 

2567 

2568 

2569 

2570 

2571 

2572 

2573 

2574 

2575 

Al 

2576 

2577 

2578 

2579 

2580 

2581 

2582 

2583 

2584 

2585 

2586 

2587 

2588 

2589 

2590 

2591 

A2 

2592 

2593 

2594 

2595 

2596 

2597 

2598 

2599 

2600 

2601 

2602 

2603 

2604 

2605 

2606 

2607 

A3 

2608 

2609 

2610 

261  1 

2612 

2613 

2614 

2615 

2616 

2617 

2618 

2619 

2620 

2621 

2622 

2623 

A4 

2624 

2625 

2626 

2627 

2628 

2629 

2630 

2631 

2632 

2633 

2634 

2635 

2636 

2637 

2638 

2639 

A5 

2640 

2641 

2642 

2643 

2644 

2645 

2646 

2647 

2648 

2649 

2650 

2651 

2652 

2653 

2654 

2655 

A6 

2656 

2657 

2658 

2659 

2660 

2661 

2662 

2663 

2664 

2665 

2666 

2667 

2668 

2669 

2670 

2671 

A7 

2672 

2673 

2674 

2675 

2676 

2677 

2678 

2679 

2680 

2681 

2682 

2683 

2684 

2685 

2686 

2687 

A8 

2688 

2689 

2690 

2691 

2692 

2693 

2694 

2695 

2696 

2697 

2698 

2699 

2700 

2701 

2702 

2703 

A9 

2704 

2705 

2706 

2707 

2708 

2709 

2710 

271  1 

2712 

2713 

2714 

2715 

2716 

2717 

2718 

271  9 

2720 

272 1 

2722 

2727 

AB 

2736 

2737 

2738 

2739 

2740 

2741 

2742 

2743 

2744 

2745 

2746 

2747 

2748 

2749 

2750 

2751 

AC 

2752 

2753 

2754 

2755 

2756 

2757 

2758 

2759 

2760 

2761 

2762 

2763 

2764 

2765 

2766 

2767 

AD 

2768 

2769 

2770 

277) 

2772 

2773 

2774 

2775 

2776 

2777 

2778 

2779 

2780 

2781 

2782 

2783 

AE 

2784 

2785 

2786 

2787 

2788 

2789 

2790 

279 1 

2792 

2793 

2794 

2795 

2796 

2797 

2798 

2799 

AF 

2800 

2801 

2802 

2803 

2804 

2805 

2806 

2807 

2808 

2809 

2810 

281 1 

2812 

2813 

2814 

2815 

BO 

2816 

2817 

2818 

2819 

2820 

2821 

2822 

2823 

2824 

2825 

2826 

2827 

2828 

2829 

2830 

2831 

Bl 

2832 

2833 

2834 

2835 

2836 

2837 

2838 

2839 

2840 

2841 

2842 

2843 

2844 

2845 

2846 

2847 

B2 

2848 

2849 

2850 

2851 

2852 

2853 

2854 

2855 

2856 

2857 

2858 

2859 

2860 

2861 

2862 

2863 

B3 

2864 

2865 

2866 

2867 

2868 

2869 

2870 

2871 

2872 

2873 

2874 

2875 

2876 

2877 

2878 

2879 

B4 

2880 

2881 

2882 

2883 

2884 

2885 

2886 

2887 

2888 

2889 

2890 

2891 

2892 

2893 

2894 

2895 

B5 

2896 

2897 

2898 

2899 

2900 

2901 

2902 

2903 

2904 

2905 

2906 

2907 

2908 

2909 

2910 

291  1 

B6 

2912 

2913 

2914 

2915 

2916 

2917 

2918 

2919 

2920 

2921 

2922 

2923 

2924 

2925 

2926 

2927 

B7 

2928 

2929 

2930 

2931 

2932 

2933 

2934 

2935 

2936 

2937 

2938 

2939 

2940 

2941 

2942 

2943 

B8 

2944 

2945 

2946 

2947 

2948 

2949 

2950 

2951 

2952 

2953 

2954 

2955 

2956 

2957 

2958 

2959 

B9 

2960 

2961 

2962 

2963 

2964 

2965 

2966 

2967 

2968 

2969 

2970 

2971 

2972 

2973 

2974 

2975 

BA 

2976 

2977 

2978 

2979 

2980 

2981 

2982 

2983 

2984 

2985 

2986 

2987 

2988 

2989 

2990 

2991 

BB 

2992 

2993 

2994 

2995 

2996 

2997 

2998 

2999 

3000 

3001 

3002 

3003 

3004 

3005 

3006 

3007 

BC 

3008 

3009 

3010 

3011 

3012 

30J3 

3014 

3015 

3016 

3017 

3018 

3019 

3020 

3021 

3022 

3023 

BD 

3024 

3025 

3026 

3027 

3028 

3029 

3030 

3031 

3032 

3033 

3034 

3035 

3036 

3037 

3038 

3039 

BE 

3040 

3041 

3042 

3043 

3044 

3045 

3046 

3047 

3048 

3049 

3050 

3051 

3052 

3053 

3054 

3055 

BF 

3056 

3057 

3058 

3059 

3060 

3061 

3062 

3063 

3064 

3065 

3066 

3067 

3068 

3069 

3070 

3071 
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TABLE  C-1.  Hexadecimal-Decimal  Integer  Conversion  {continued) 


0 

1 

2 

3 

5 

6 

7 

8 

9 

A 

B 

C 

D 

E 

F 

CO 

3072 

3073 

3074 

3075 

3076 

3077 

3078 

3079 

3080 

3081 

3082 

3083 

3084 

3085 

3086 

3087 

C  l 

3088 

3089 

3090 

3091 

3092 

3093 

3094 

3095 

3096 

3097 

3098 

3099 

3100 

3101 

3102 

3103 

C2 

3104 

3105 

3106 

3107 

3108 

3109 

3110 

31 11 

3112 

3113 

3114 

31 15 

3116 

31  17 

3118 

3119 

C3 

3120 

3121 

3122 

3123 

3124 

3125 

3126 

3127 

3128 

3129 

3130 

3131 

3132 

3133 

3134 

3135 

C4 

3136 

3137 

3138 

3139 

3140 

3141 

3142 

3143 

3144 

3145 

3146 

3147 

3148 

3149 

3150 

3151 

C5 

3152 

3153 

3154 

3155 

3156 

3157 

3158 

3159 

3160 

3161 

3162 

3163 

3164 

3165 

3166 

3167 

C6 

3168 

3169 

3170 

3171 

3172 

3173 

3174 

3175 

3176 

3177 

3178 

3179 

3180 

3181 

3182 

3183 

C7 

3184 

3185 

3186 

3187 

3188 

3189 

3190 

3191 

3192 

3193 

3194 

3195 

3196 

3197 

3198 

3199 

C8 

3200 

3201 

3202 

3203 

3204 

3205 

3206 

3207 

3208 

3209 

3210 

3211 

3212 

3213 

3214 

3215 

C9 

3216 

3217 

3218 

3219 

3220 

3221 

3222 

3223 

3224 

3225 

3226 

3227 

3228 

3229 

3230 

2231 

CA 

3232 

3233 

3234 

3235 

3236 

3237 

3238 

3239 

3240 

3241 

3242 

3243 

3244 

3245 

3246 

3247 

CB 

3248 

3249 

3250 

3251 

3252 

3253 

3254 

3255 

3256 

3257 

3258 

3259 

3260 

3261 

3262 

3263 

CC 

3264 

3265 

3266 

3267 

3268 

3269 

3270 

3271 

3272 

3273 

3274 

3275 

3276 

3277 

3278 

3279 

CD 

3280 

3281 

3282 

3283 

3284 

3285 

3286 

3287 

3288 

3289 

3290 

3291 

3292 

3293 

3294 

3295 

C  E 

3296 

3297 

3298 

3299 

3300 

3301 

3302 

3303 

3304 

3305 

3306 

3307 

3308 

3309 

331 0 

33 1  1 

CF 

3312 

3313 

3314 

3315 

3316 

3317 

3318 

3319 

3320 

3321 

3322 

3323 

3324 

3325 

3326 

3327 

DO 

3328 

3329 

3330 

3331 

3332 

3333 

3334 

3335 

3336 

3337 

3338 

3339 

3340 

3341 

3342 

3343 

Dl 

3344 

3345 

3346 

3347 

3348 

3349 

3350 

3351 

3352 

3353 

3354 

3355 

3356 

3357 

3358 

3359 

D2 

3360 

3361 

3362 

3363 

3364 

3365 

3366 

3367 

3368 

3369 

2370 

3371 

3372 

3373 

3374 

3375 

D3 

3376 

3377 

3378 

3379 

3380 

3381 

3382 

3383 

3384 

3385 

3386 

3387 

3388 

3389 

3390 

339  i 

D4 

3392 

3393 

3394 

3395 

3396 

3397 

3398 

3399 

3400 

3401 

3402 

3403 

3404 

3405 

3406 

3407 

D5 

3408 

3409 

3410 

341 1 

3412 

3413 

3414 

3415 

3416 

3417 

3418 

3419 

3420 

3421 

3422 

3423 

D6 

3424 

3425 

3426 

3427 

3428 

3429 

3430 

3431 

3432 

3433 

3434 

3435 

3436 

3437 

3438 

3439 

D7 

3440 

3441 

3442 

3443 

3444 

3445 

3446 

3447 

3448 

3449 

3450 

3451 

3452 

3453 

3454 

3455 

D8 

3456 

3457 

3458 

3459 

3460 

3461 

3462 

3463 

3464 

3465 

3466 

3467 

3468 

3469 

3470 

3471 

D9 

3472 

3473 

3474 

3475 

3476 

3477 

34  7  8 

3479 

3480 

3481 

3482 

3483 

3484 

3485 

3486 

3487 

DA 

3488 

3489 

3490 

3492 

3493 

3498 

3500 

350 1 

3502 

3503 

DB 

3504 

3505 

3506 

3507 

3508 

3509 

3510 

3511 

3512 

3513 

3514 

3515 

3516 

3517 

3518 

3519 

DC 

3520 

3521 

3522 

3523 

3524 

3525 

3526 

3527 

3528 

3529 

3530 

3531 

3532 

3533 

3534 

3535 

DD 

3536 

3537 

3538 

3539 

3540 

3541 

3542 

3543 

3544 

3545 

3546 

3547 

3548 

3549 

3550 

3551 

DE 

3552 

3553 

3554 

3555 

3556 

3557 

3558 

3559 

3560 

356 1 

3562 

3563 

3564 

3565 

3566 

3567 

DF 

3568 

3569 

3570 

3571 

3572 

3573 

3574 

3575 

3576 

3577 

3578 

3579 

3580 

3581 

3582 

3583 

EO 

3584 

35  85 

3586 

3587 

3588 

3589 

3590 

3591 

3592 

3593 

3594 

3595 

3596 

3597 

3598 

3599 

E  ] 

3600 

3601 

3602 

3603 

3604 

3605 

3606 

3607 

3608 

3609 

361 0 

36 1  1 

361  2 

3613 

3614 

3615 

E2 

3616 

3617 

3618 

3619 

3620 

3621 

3622 

3623 

3624 

3625 

3626 

3627 

3628 

3629 

3630 

3631 

E3 

3632 

363  3 

3634 

3635 

3636 

3637 

3638 

3639 

3640 

3641 

3642 

3643 

3644 

3645 

3646 

3647 

E4 

3648 

3649 

3650 

3651 

3652 

3653 

3654 

3655 

3656 

3657 

3658 

3659 

3660 

3661 

3662 

3663 

E5 

3664 

3665 

3666 

3667 

3668 

3669 

3670 

3671 

36  7  2 

3673 

3674 

3675 

36  7  6 

3677 

3678 

3679 

E6 

3680 

3681 

368  2 

3683 

3684 

3685 

3686 

3687 

3688 

36  89 

3690 

3691 

3692 

3693 

3694 

3695 

E7 

3696 

3697 

3698 

3699 

3700 

3701 

3702 

3703 

3704 

3705 

3706 

3707 

3708 

3709 

3710 

371 1 

E8 

3712 

3713 

3714 

3715 

3716 

3717 

3718 

3719 

3720 

3721 

3722 

3723 

3724 

3725 

3726 

3727 

E9 

3728 

3729 

3730 

3731 

3732 

3733 

3734 

3735 

3736 

3737 

3738 

3739 

3740 

3741 

3742 

3743 

EA 

3744 

3745 

3746 

3747 

3748 

3749 

3750 

3751 

3752 

3753 

3754 

3755 

3756 

3757 

3758 

3759 

EB 

3760 

3761 

3762 

3763 

3764 

3765 

3766 

3767 

3768 

376? 

3770 

3771 

3772 

3773 

3774 

3775 

EC 

3776 

3777 

3778 

3779 

3780 

3781 

3782 

3783 

3784 

3785 

3786 

3787 

3788 

3789 

3790 

3791 

EC 

3792 

3793 

3794 

3795 

3796 

3797 

3798 

3799 

3800 

3801 

3802 

3803 

3804 

3805 

3806 

3807 

EE 

3808 

3809 

3810 

3811 

3812 

3813 

3814 

3815 

3816 

3817 

3818 

3819 

3820 

3821 

3822 

3823 

EF 

3824 

3825 

3826 

3827 

3828 

3829 

3830 

3831 

3832 

3833 

3834 

3835 

3836 

3837 

3838 

3839 
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TABLE  C-1.  Hexadecimal-Decimal  Integer  Conversion  (continued) 


0 

l 

2 

3 

4 

5 

6 

7 

8 

9 

A 

B 

C 

D 

E 

F 

FO 

3840 

384 1 

3842 

3843 

3844 

3845 

3846 

3847 

3848 

3849 

3850 

3851 

3852 

3853 

3854 

3855 

Fl 

3856 

3857 

3858 

3859 

3860 

386 1 

3862 

3863 

3864 

3865 

3866 

3867 

3868 

3869 

3870 

3871 

F2 

3872 

3873 

3874 

3875 

3876 

3877 

3878 

3879 

3880 

3881 

3882 

3883 

3884 

3885 

3886 

3887 

F3 

3888 

3889 

3890 

3891 

3892 

3893 

3894 

3895 

3896 

3897 

389C 

3899 

3900 

3901 

3902 

3903 

F4 

3904 

3905 

3906 

3907 

3908 

3909 

39I0 

391  \ 

3912 

3913 

3914 

3915 

3916 

3917 

3918 

3919 

F5 

3920 

392 1 

3922 

3923 

3924 

3925 

3926 

3927 

3928 

3929 

3930 

3931 

3932 

3933 

3934 

3935 

F6 

3936 

3937 

3938 

3939 

3940 

394 1 

3942 

3943 

3944 

3945 

3946 

3947 

3948 

3949 

3950 

3951 

F7 

3952 

3953 

3954 

3955 

3956 

3957 

3958 

3959 

3960 

3961 

3962 

3963 

3964 

3965 

3966 

3967 

F8 

3968 

3969 

3970 

397 1 

3972 

3973 

3974 

3975 

3976 

3977 

3978 

3979 

3980 

3981 

3982 

3983 

F9 

3984 

3985 

3986 

3987 

3988 

3989 

3990 

3991 

3992 

3993 

3994 

3995 

3996 

3997 

3998 

3999 

F* 

4000 

400 1 

4002 

4003 

4004 

4005 

4006 

4007 

4008 

4009 

4010 

401  1 

4012 

4013 

4014 

4015 

FB 

4016 

4017 

4018 

4019 

4020 

402 1 

4022 

4023 

4024 

4025 

4026 

4027 

4028 

4029 

4030 

4031 

FC 

4032 

4033 

4034 

4035 

4036 

4037 

4038 

4039 

4040 

4041 

4042 

4043 

4044 

4045 

4046 

4047 

FO 

4048 

4049 

4050 

405 1 

4052 

4053 

4054 

4055 

4056 

4057 

4058 

4059 

4060 

4061 

4062 

4063 

FE 

4064 

4065 

4066 

4067 

4068 

4069 

4070 

4071 

4072 

4073 

4074 

4075 

4076 

4077 

4078 

4079 

FF 

4080 

408 1 

4082 

4083 

4084 

4085 

4086 

4087 

4088 

4089 

4090 

4091 

4092 

4093 

4094 

4095 

TABLE  C-2.  Conversion  Values 


Hexadecimal 

Decimol 

Hexadecimal 

Decimal 

Hexadecimal 

Decimal 

Me*odecimol 

Decimal 

01  000 

4  096 

11  000 

69  632 

30  000 

1 96  608 

400  000 

4  1 94  304 

02  000 

8  192 

12  000 

73  728 

40  000 

262  144 

500  000 

5  242  880 

03  000 

12  288 

13  000 

77  824 

50  000 

327  680 

600  000 

6  291  456 

04  000 

16  384 

14  000 

81  920 

60  000 

393  216 

700  000 

7  340  032 

05  000 

20  480 

15  000 

86  016 

70  000 

458  752 

800  000 

8  388  608 

06  000 

24  576 

16  000 

90  1 12 

80  000 

524  288 

900  000 

9  437  184 

07  000 

28  672 

17  000 

94  208 

90  000 

589  824 

A 00  000 

10  485  760 

08  000 

32  768 

18  000 

98  304 

AO  000 

655  360 

BOO  000 

11  534  336 

09  000 

36  864 

19  000 

102  400 

BO  000 

720  896 

COO  000 

12  582  912 

OA  000 

40  960 

1A  000 

1 06  496 

CO  000 

786  432 

D00  000 

13  631  488 

0B  000 

45  056 

IB  000 

1 1 0  592 

DO  000 

851  968 

E00  000 

14  680  064 

OC  000 

49  152 

1C  000 

114  688 

EO  000 

917  504 

F00  000 

15  728  640 

OD  000 

53  248 

ID  000 

1 18  784 

FO  000 

983  040 

1  000  000 

16  777  216 

OE  000 

57  344 

IE  000 

122  880 

100  000 

1  048  576 

2  000  000 

33  554  432 

OF  000 

61  440 

IF  000 

1 26  976 

200  000 

2  097  152 

10  000 

65  536 

20  000 

131  072 

300  000 

3  145  728 

3.  Multiply  the  decimal  equivalent  by  16 


13 

278 

195 

X  596 

046 

448  X  1016 

0.791 

442 

09610 

Decimal  fractions  may  be  converted  to  hexadecimal  fractions  by  succes- 
sively multiplying  the  decimal  fraction  by  1610.  After  each  multiplication,  the 
integer  portion  is  removed  to  form  a  hexadecimal  fraction  by  building  to  the 
right  of  the  hexadecimal  point.  However,  since  decimal  arithmetic  is  used  in 
this  conversion,  the  integer  portion  of  each  product  must  be  converted  to 
hexadecimal  numbers. 
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TABLE  C- 3.  Deriving  Mathematical  Functions 


Function 

VIC  BASIC  Equivalent 

Secant 

SEC(X)  =  l/COS(X) 

Cosecant 

CSC(X)=  1/SIN(X) 

Cotangent 

COT(X)=  1/TAN(X) 

Inverse  sine 

ARCSIN(X)  =  ATN(X/SQR(  -  X*X  +  1)) 

Inverse  cosine 

ARCCOS(X)  =  —  ATN(X/SQR 

(-X*X  +  1))  +  tt/2 

Inverse  secant 

ARCSEC(X)  =  ATN(X/SQR(X*X  -  I)) 

Inverse  cosecant 

ARCCSC(X)=  ATN(X/SQR(X*X-  1)) 

+  (SGN(X)  -  1)*  tt/2 

Inverse  cotangent 

ARCOT(X)  =  ATN(X)  +  tt/2 

Hyperbolic  sine 

SINE(X)  =  (EXP(X)  -  EXP(-  X))/2 

Hyperbolic  cosine 

COSH(X)  =  (EXP(X)  +  EXP(  -  X))/2 

Hyperbolic  tangent 

TANH(X)  =  EXP(  -  X)/EXP(X)  +  EXP 

(-X))*2  +  1 

Hyperbolic  secant 

SECH(X)  =  2/(EXP(X)  +  EXP(  -  X) 

Hyperbolic  cosecant 

CSCH(X)  =  2/(EXP(X)  -  EXP(  -  X)) 

Hyperbolic  cotangent 

COTH(X)=  EXP(-  X)/(EXP(X) 

-  EXP(  -  X)*2  +  1 

Inverse  hyperbolic  sine 

ARCSINH(X)  =  LOG(X  +  SQR(X*X  +  1) 

Inverse  hyperbolic  cosine 

ARCCOSH(X)  =  LOG(X  +  SQR(X*X  -  1) 

Inverse  hyperbolic  tangent 

ARCTANH(X)  =  LOG((l  +  X)/(I  -  X))/2 

Inverse  hyperbolic  secant 

ARCSECH(X)  =  LOG((SQR 

(-  X*X  +  1)+  1/X) 

Inverse  hyperbolic  cosecant 

ARCCSCH(X)  =  LOG((SGN(X)*SQR 

(X*X  +  1)/X 

Inverse  hyperbolic  cotangent 

ARCCOTH(X)=  LOG((X  +  1)/(X  -  l))/2 

Example: 

Convert  0.89510  to  its  hexadecimal  equivalent 

0.895 
 16 

14.320 
 16 

5.120 
 16 

1.920 
 16 

O.E51E16  14.720 

Functions  that  are  not  intrinsic  to  C-128  BASIC  may  be  calculated  as  in  Table 
C-3. 
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Sound  and  Display 
Characters  and  Codes 


Two  of  the  more  powerful  functions  of  the  C-128  are  its  display  and  sound 
generation  capabilities.  The  tables  in  this  appendix  cover  all  of  the  C-128 
character  codes,  screen  POKE  values,  and  sound  register  equivalents. 

Table  D-l  covers  all  of  the  characters  and  functions  that  are  displayed 
using  the  CHR$  instruction.  In  many  instances,  the  use  of  the  CHR$  function 
is  optional;  however,  some  functions,  such  as  RETURN  and  RUN/  STOP,  are  not 
programmable  with  the  PRINT  function.  To  program  using  these  functions 
you  will  need  to  use  the  CHR$  function  and  the  codes  in  this  table. 
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The  codes  used  in  the  CHR$  instruction  are  not  the  same  as  those  used  in 
the  POKE-to-screen  commands.  The  codes  shown  in  Table  D-2  are  listed  in 
the  same  order  as  the  characters  in  memory.  Notice  that  all  of  the  control 
characters  are  omitted  from  this  list.  This  is  because  there  is  no  display  code 
for  them;  control  codes  use  the  codes  of  standard  reverse  characters  (for 
example,  reverse-heart  for  CLR  HOME). 

Table  D-3  presents  the  POKE  values  and  frequencies  of  musical  notes. 


TABLE  D-1.  C-128  Character  Codes 


Prints  CHR$ 

0 
l 
2 
3 
4 

WHT  5 
6 
7 

DISABLE  8 
SHIFT 

ENABLE  9 
SHIFT 

10 
ll 
12 


Prints  CHR$ 

RETURN  13 

SWITCH  14 
TO 

LOWER-  15 
CASE 

16 

CURSOR  i  17 
RVS  ON  18 
CLR  HOME  19 
INS  DEL  20 
21 
22 
23 
24 
25 
26 


Prints  CHR$ 

27 
28 
29 
30 


RED 

CURSOR  - 
GRN 


BLU 

|  W  | 

|TT| 

i 

m 

M 

m 


31 
32 
33 
34 
35 
36 
37 
38 
39 
40 


Prints 


e 

III 

121 
131 

a 
m 


CHR$ 

41 
42 
43 
44 
45 
46 
47 
48 
49 
50 
51 
52 
53 
54 
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TABLE  D-1.  C-128  Character  Codes  (continued) 


Prints 

CHR$ 

Prints 

CHR$ 

Prints 

CHR$ 

Prints 

CHR$ 

I7I 

55 

IEI 

75 

L_!  1 

95 

I   ■  l 

115 

00 

56 

1LI 

76 

— 

!  1 

96 

c 

116 

(1 

57 

111 

77 

11 

97 

117 

58 

INI 

78 

ITJ 

98 

118 

59 

101 

79 

-H 

1  1 

99 

O 

119 

60 

80 

— 

100 

151 

120 

61 

Q 

81 

101 

n 

1  mi 

121 

[>l 

62 

R 

82 

H 

102 

+ 

L„TJ 

122 

L?l 

63 

83 

i ! 
ii  i 

103 

+ 

123 

S3 

64 

m 
i  ■ 

84 

m 

LJJ 

104 

£D 

124 

I'fti 

■  ■ 

65 

!V!J 

85 

ru 

105 

m 

LJJ 

125 

R 

66 

(Ul 

1 VJ 

86 

L  1 

106 

126 

67 

u 

87 

r  i 

107 

•m 

127 

D 

68 

DO 

ran 

1X1 

88 
oo 

lUo 

SEI 

Oy 

T 

8Q 

oy 

ft! 

1  AO 

OR  A 

1/7 

IF| 

71 

y\j 

It) 

1  1U 

1  J\J 

G| 

71 

E 

91 

c 

111 

131 

[HI 

72 

92 

n 

112 

132 

ill 

73 

[31 

93 

SI 

113 

Fl 

133 

Ul 

74 

94 

a 

114 

F3 

134 
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TABLE  D-1.  C-128  Character  Codes  {continued) 


Prints  CHR$ 

Prints 

o  rv  3 

Pri  ntc 

rnnis 

Prints 
x  i  mis 

ruDC 

F5 

135 

LT  BLUE 

154 

-I 

174 

Tl 

LJ_J 

194 

F7 

136 

LT  GRAY 

155 

1  I 

175 

— 

i  i 

195 

F2 

137 

PUR 

156 

ffl 

I  /u 

1  ! 

F4 

138 

CRSR- 

157 

ffl 

177 

n 

197 

F6 

139 

YEL 

158 

T 

178 

— 

198 

F8 

140 

CYN  SPACE  159 

hTI 

179 

ii 

■ 

199 

SHIFT- 

n 

160 

n 

■  i 

180 

m 

200 

RETURN 

141 

SWITCH  TO 

ri 

161 

in 

181 

kl 

201 

UPPERCASE 

142 

y 

162 

□ 

1  ■ 

182 

\S 

i  i 

202 

143 

n 

163 

H 

183 

PI 

r 

203 

BLK 

144 

□ 

164 

n 

i  i 

184 

u 

204 

CURSOR  r 

145 

□ 

165 

185 

N 

L_.  j| 

205 

RVS  OFF 

146 

166 

186 

206 

CLR  HOME 

147 

1 

167 

■J 

187 

i  i 

207 

INS  DEL 

148 

V. 

168 

rm 

188 

n 

i  i 

208 

BROWN 

149 

B 

169 

ffl 

189 

■ 

209 

LT  RED 

150 

□ 

170 

E 

190 

— 

210 

DK  GRAY 

151 

IS 

171 

H 

191 

m 

211 

MED  GRAY 

152 

J 

172 

H 

192 

212 

LT  GREEN 

153 

173 

* 

193 

213 
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TABLE  D-1.  C-128  Character  Codes  (continued) 


Prints 

CHR$ 

Prints 

CHR$ 

Prints 

CHR$ 

Prints 

CHR$ 

X 

214 

E 

225 

□ 

236 

n 

247 

o 

215 

y 

226 

i  i 

237 

H 

1  1 

248 

216 

n 

1  1 

227 

SI 

L_BJ 

238 

y 

249 

□ 

I  BJ 

217 

□ 

228 

□ 

239 

□ 

250 

♦ 

218 

n 

229 

i  ii 

240 

□ 

■  1 

251 

+ 

LB  I 

219 

LMZB 

230 

i  i 

241 

□ 

l  I 

252 

B 

220 

□ 

231 

H 

242 

ffl 

253 

1] 

221 

232 

II 

243 

H 

254 

222 

233 

D 

244 

255 

223 

□ 

234 

C 

245 

□ 

224 

EE 

235 

□ 

246 
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TABLE  D-2.  Screen  Codes 


Set  1 

Set  2 

POKE 

Set  1 

Set  2 

POKE 

Set  1 

Set  2  POKE 

II 

0 

\T\ 

SI 

20 

40 

SB 

a 

1 

IU] 

u 

21 

41 

Ml 

5b] 

2 

I5J 

22 

* 

1  

42 

IC'i 

c 

3 

u 

23 

43 

PI 

d 

4 

LlJLJ 

x 

24 

44 

E 

e 

5 

[VI 

1  ■  1 

y 

25 

— 

45 

IF! 

6 

1^— 1 

Izl 

26 

[7 

1  5  

46 

IGI 

7 

!"f| 

^™  1 

27 

|X 

1  ™ 

47 

m 

IB 

8 

28 

6 

48 

fl] 

i 

9 

ITI 

29 

IX 

49 

[Jl 

fjl 

10 

r+i 

30 

[Z 

50 

IK] 

k 

ITH 

31 

51 

ILI 

IV 

12 

32 

14 

52 

M 

M 

13 

33 

15 

53 

INI 

n 

14 

I  l 

34 

G 

54 

rni 

15 

M 

35 

17 

55 

m 

16 

is] 

36 

8 

56 

Q 

SI 

17 

IK] 

37 

9 

57 

[Ri 

(rJ 

18 

6 

38 

58 

IS] 

Is| 

19 

|""dTj 

39 

s: 

59 
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TABLED -2.  Screen  Codes  (continued) 


Set  1 

Set  2 

POKE 

Set  1 

Set  2 

POKE 

Set  1       Set  2 

POKE 

!■£] 

i  

60 

L 

E 

80 

□ 

100 

61 

• 

19 

81 

□ 

101 

62 

_ 

Si 

82 

si 

102 

63 

m 

m 

83 

□ 

103 

H 

64 

hi 

II 

84 

104 

11 

65 

ra 

85 

B 

105 

II 

66 

X 

SI 

i  T  i 

86 

□ 

106 

H 

67 

o 

1  1 

M 

87 

107 

1  1 

1  1 

68 

[51 

I  *  l 

LEJL 

88 

108 

I  1 

IB 

69 

1  M.I 

1  "  1 

89 

i  1 

109 

— 

IB 

70 

+ 

1  T| 

IZ1 

90 

ru 

110 

LLI 

71 

+ 

91 

n 

111 

m 

LLI 

H 

72 

B 

LB  1 

92 

i  n 

112 

ru 

ITI 

73 

H 

i  ■  1 

93 

ffl 

113 

ITI 

■■J  | 

74 

ss 

94 

-r 

114 

i  i 

IKI 

75 

1  3 

s> 

95 

ai 

115 

i_ 

L 

76 

96 

□ 

116 

s 

m 

77 

E 

97 

E 

117 

m 

78 

a 

98 

118 

c 

m 

79 

H 

99 

n 

119 
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TABLE  D-2.  Screen  Codes  (continued) 


Set  1 

Set  2 

aet  I      set  l 

r  U1V1L 

set  i     a>et  z 

H 

120 

E 

123 

E 

126 

U 

121 

□ 

124 

S 

127 

□ 

0 

122 

ffl 

125 

NOTE:  Numbers  128  through  255  of  the  screen  codes  are  reverse  video  of  numbers  0 
through  127. 


Table  D-3=  POKE  Values,  Frequencies,  and  Musical  Equivalents 


Upper  Tone 

Lower  Tone 

Decimal 

Frequency 

Musical 

POKE  Value 

POKE  Value 

Values 

Produced 

Note 

OCTAVE  ONE 

12 

268 

16  Hz 

C 

28 

284 

17  Hz 

C# 

45 

301 

18  Hz 

D 

62 

318 

19  Hz 

D# 

81 

337 

21  Hz 

E 

101 

357 

22  Hz 

F 

123 

379 

23  Hz 

F# 

145 

401 

24  Hz 

G 

169 

425 

25  Hz 

G# 

195 

451 

27  Hz 

A 

221 

477 

29  Hz 

A# 

250 

506 

31  Hz 

B 

OCTAVE  TWO 

2 

24 

536 

32  Hz 

C 

2 

56 

568 

34  Hz 

C# 

2 

90 

602 

37  Hz 

D 

2 

125 

637 

39  Hz 

D# 

2 

163 

675 

41  Hz 

E 

2 

203 

715 

44  Hz 

F 

2 

246 

758 

46  Hz 

F# 

3 

35 

803 

49  Hz 

G 
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TABL£  D-3.  POKE  Values,  Frequencies,  and  Musical  Equivalents  (continued) 


Upper  Tone 

Lower  Tone 

Decimal 

Frequency 

Musical 

POKE  Value 

POKE  Value 

Values 

Produced 

Note 

3 

83 

OC  1 

851 

^7  IJ-F 

5Z  HZ 

Kin 

3 

134 

902 

r ^  tt_ 

55  Hz 

A 

A 

3 

1  C7 
10  / 

955 

CO  IT, 

5o  Hz 

At? 

3 

^A  A 

Z44 

1U12 

£7 

OZ  HZ 

r> 

r> 

OCTAVE  THREE 

4 

48 

1072 

65  Hz 

c 

4 

112 

1136 

69  Hz 

c# 

4 

180 

1204 

73  Hz 

D 

4 

251 

1275 

76  Hz 

D# 

5 

71 

1351 

82  Hz 

E 

5 

1  C  1 

151 

1431 

O  "7  TT, 

87  Hz 

r 

5 

23  / 

151  / 

m  tj™ 
VZ  HZ 

rff 

c 
0 

/  1 

1  £LC\TI 

no  Ur, 
95  HZ 

0 

lo  / 

1  /U3 

1    (\A  Ur, 

1U4  Hz 

Off 

1 

1 1 

lz 

i  ofM 
loU4 

1 1U  Hz 

A 

n 

1 

i  i  n 
1  IV 

mil 
[y  1 1 

1    1  *7  Ur. 
11/  HZ 

Aff 

1 

233 

ZUz5 

1  ">  1  u  _ 

1Z3  Hz 

r> 

B 

OCTAVE  FOUR 

8 

97 

2145 

131  Hz 

c 

8 

225 

2273 

139  Hz 

c# 

9 

104 

2408 

147  Hz 

D 

9 

247 

2551 

156  Hz 

D# 

10 

143 

2703 

165  Hz 

E 

1 1 
i  i 

Al 
4/ 

ZoOJ 

1  7^ 

1  ID  HZ 

t7 

r 

7  1  Q 
Zlo 

ir\iA 

JUJ4 

1  8<\  Ur/ 

153  HZ 

rff 

1 7 

1Z 

14Z 

jZ14 

IVO  HZ 

VJ 

i  j 

77 

J4UJ 

7H8  14  v 
ZUo  rlZ 

Off 

\A 
14 

Z4 

joUo 

77H 

ZZU  HZ 

A 

A 

\A 
14 

Zjo 

1C77 
JoZZ 

111 

Zjj  HZ 

/\rr 

1  c 
ID 

7 1  n 
Z1U 

4U5U 

7J7  H7 
Z4/  HZ 

T> 

OCTAVE  FIVE 

16 

195 

4291 

262  Hz 

c 

17 

194 

4546 

277  Hz 

c# 

18 

208 

4816 

294  Hz 

D 

19 

238 

5102 

311  Hz 

D# 

21 

30 

5406 

330  Hz 

E 

22 

95 

5727 

349  Hz 

F 

23 

180 

6068 

370  Hz 

F# 

25 

29 

6429 

392  Hz 

G 

26 

155 

6811 

415  Hz 

G# 
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TABLE  D-3.  POKE  Values,  Frequencies,  and  Musical  Equivalents  {continued) 


1  nnpr  Tnn*» 
UJJUcI  xiillc 

T  nwpr  Tnnp 

L/cti  ill  al 

r  IcLjUcIlLj 

iVIUMLal 

POKF  Valup 
»  yj rv Tdiuc 

POKF  Value 

Vjilu.es 

Produced 

28 

48 

7216 

440  Hz 

A 

29 

221 

7645 

466  Hz 

A# 

31 

164 

8100 

494  Hz 

B 

OCTAVE  SIX 

33 

134 

8582 

523  Hz 

C 

35 

132 

9092 

554  Hz 

C# 

37 

161 

9633 

587  Hz 

D 

39 

221 

10205 

622  Hz 

D# 

42 

60 

10812 

659  Hz 

E 

44 

191 

11455 

698  Hz 

F 

47 

104 

12136 

740  Hz 

F# 

50 

58 

12858 

784  Hz 

G 

53 

55 

13623 

831  Hz 

G# 

56 

97 

14433 

880  Hz 

A 

59 

187 

15291 

932  Hz 

A# 

63 

72 

16200 

988  Hz 

B 

OCTAVE  SEVEN 

67 

12 

17164 

1046  Hz 

C 

71 

8 

18184 

1109  Hz 

C# 

75 

66 

19266 

1175  Hz 

D 

79 

187 

20411 

1244  Hz 

D# 

84 

121 

21625 

1319  Hz 

E 

89 

127 

22911 

1397  Hz 

F 

94 

209 

24273 

1480  Hz 

F# 

100 

117 

25717 

1568  Hz 

G 

106 

110 

27246 

1661  Hz 

G# 

112 

194 

28866 

1760  Hz 

A 

119 

118 

30582 

1865  Hz 

A# 

126 

145 

32401 

1976  Hz 

B 

OCTAVE  EIGHT 

134 

24 

34328 

2093  Hz 

c 

142 

17 

36369 

2217  Hz 

C# 

150 

132 

38532 

2349  Hz 

D 

159 

119 

40823 

2489  Hz 

D# 

168 

242 

43250 

2637  Hz 

E 

178 

254 

45822 

2794  Hz 

F 

189 

163 

48547 

2960  Hz 

F# 

200 

234 

51434 

3136  Hz 

G 

212 

220 

54492 

3322  Hz 

G# 

225 

132 

57732 

3520  Hz 

A 

238 

237 

61165 

3729  Hz 

A# 

253 

34 

64802 

3951  Hz 

B 

 APPENDIX 

BASIC  Statements 


This  appendix  explains  the  syntax  of  all  the  C-128  BASIC  statements.  They 
are  presented  in  alphabetical  order  and  include  both  internal  functions  and 
I/O  commands. 

APPEND 

The  APPEND#  statement  opens  an  existing  sequential  diskette  file  and 
allows  new  data  to  be  added  at  the  end  of  the  file. 

Format: 

APPEND#//7?/entfm^[,DJ][ON  Uz] 

The  APPEND#  statement  opens  sequential  data  file  filename  on  the 
diskette  in  drive  d  and  positions  file  pointers  beyond  the  current  end  of  file. 
Subsequent  PRINT#  statements  referencing  logical  file  If  can  then  write 
additional  data,  which  gets  appended  to  the  end  of  the  file.  If  no  disk  drive  is 
specified  (d  is  absent)  drive  0  is  assumed. 


461 


462    C-128  USER  GUIDE 


Example: 

Open  sequential  file  "CALC'as  logical  file  #7  on 
drive  0.  Write  variable  A  contents  to  the  end 
of  the  file 

Open  sequential  file  "TALK"  as  logical  file  #5.  The 
string  "123  "  is  added  to  the  end  of  the  file 

AUTO 

Initiates  auto  line  numbering.  The  number  that  follows  AUTO  indicates 
the  line  increments. 

Example: 

AUTO  10 

This  will  start  incrementing  your  lines  in  10's  after  you  enter  the  first  line  of 
your  program. 

BACKUP 

The  BACKUP  statement  duplicates  an  entire  diskette.  The  duplicate  and 
original  have  the  same  header,  disk  name,  identification  number,  directory, 
and  files*. 

Format: 

BACKUP  Ds  TO  Dd  [ON  Uz] 

The  diskette  in  drive  s  is  duplicated.  The  duplicate  diskette  is  generated 
in  drive  d.  Duplicating  the  entire  diskette  takes  a  couple  of  minutes. 

Example: 

BACKUP  D0  TO  Dl         Duplicate  contents  of  diskette  in  drive  0  to  diskette 
in  drive  1 

BACKUP  D 1  TO  PA         Duplicate  contents  of  diskette  in  drive  1  to  diskette 
in  drive  0 

Caution:  All  files  on  the  diskette  must  be  properly  closed  before  the 
diskette  is  backed  up. 

BANK 

Switches  the  system  from  one  bank  to  another.  Options  (0-15).  The 


APPENDS, "CALC" 
-RINT#1,A 


fiPPEND#3,  "TfiLK'MH 
PRINT#3, "123" 
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default  bank  is  15.  The  only  BASIC  commands  affected  by  BANK  are  PEEK, 
POKE,  SYS,  and  USR. 

Example: 

BANK  12 

Switches  the  system  from  the  current  memory  bank  to  bank  12. 
BEGIN 

Signals  the  start  of  a  conditional  subroutine.  Similar  to  IF/  THEN,  but 
allows  you  to  include  several  line  numbers  between  BEGIN  and  BEND. 

Example: 

10  IF  A<  =  12  THEN  BEGIN:   PRINT  "THIS  IS  A  VALID 

MONTH" 
20  PRINT  A* (A) 
30  BEND:   GOTO  50 
40  PRINT   "NOT  A  VALID  MONTH" 
50  END 

BEND 

Signals  the  end  of  a  BEGIN/  BEND  subroutine.  (See  BEGIN.) 
BLOAD 

Loads  a  binary  file  from  disk  or  tape. 

Format: 

BLOAD  "filename" 

Example: 

BLOAD   " CHARACTERS " 

BOOT 

Loads  a  binary  program  and  runs  it. 
Example: 

BOOT  "WRDPROC" 

This  loads  and  runs  a  machine  language  program  named  WRDPROC. 

BOX 

Draws  a  box  in  the  selected  position  and  size. 
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Format: 

BOX  C,  XA,  YA,  XB,  YB,  R,  F 

where  C  is  the  box  color,  XA  and  YA  locate  the  upper  left-hand  corner  of  the 
box,  XB  and  YB  locate  the  lower  right-hand  corner  of  the  box,  R  is  the 
rotation  angle  (0  is  no  rotation),  and  Fis  fill  (Y/N). 

BSAVE 

Saves  a  binary  program  or  data  file  on  disk  or  tape. 
Format: 

BSAVE  "filename'",  B  banktt,  P  start  address,  TO  P  end  address 
CATALOG 

Same  as  directory  command  —  displays  the  contents  of  the  disk. 

Format: 

CATALOG 

CHAR 

Prints  text  on  the  graphics  screen. 

Format: 

CHAR  C,  X,  Y,  "text",  R 

where  C  is  the  text  color,  X and  Fare  the  line  column  and  row  positions;  text 
is  the  text  you  want  printed  on  the  screen,  and  R  is  reverse/ non-reverse. 

CIRCLE 

Draws  a  circle  in  the  selected  position  and  size. 
Format: 

CIRCLE  C,  X,  Y,  XR,  YR,  B,  E,  L 

where  C  is  the  box  color,  X  and  Y  locate  the  center  of  the  circle,  XR  and  YR 
specify  the  x  and  y  radii,  B  is  the  beginning  arc  angle,  £is  the  ending  arc  angle, 
R  is  the  rotation  of  the  circle,  and  L  is  the  length  of  the  sides  (if  any). 

NOTE:  If  you  specify  a  side  length  (L)  then  the  circle  will  become  a 
polygon  with  the  number  of  sides  determined  by  360/ L. 
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CLOSE 

The  CLOSE  statement  closes  a  logical  file. 

Format: 

CLOSE  If 

The  CLOSE  statement  closes  logical  file  If.  Every  file  should  be  closed 
after  all  file  accesses  have  been  completed.  An  open  logical  file  may  be  closed 
only  once.  The  particular  operations  performed  in  response  to  a  CLOSE 
statement  depend  on  the  open  file's  physical  device  and  the  type  of  access  that 
occurred. 

Example: 

CLOSE  1  Close  logical  file  1 

CLOSE  14         Close  logical  file  14 

cut 

The  CLR  statement  sets  all  numeric  variables  to  zero  and  assigns  null 
values  to  all  string  variables.  All  array  space  in  memory  is  released.  This  is 
equivalent  to  turning  the  computer  OFF,  then  turning  it  back  ON  and  reload- 
ing the  program  into  memory.  CLR  closes  all  logical  files  that  are  currently 
open  within  the  executing  program. 

Format: 
CLR 

A  program  will  continue  to  run  following  execution  of  a  CLR  statement 
if  the  statement's  execution  does  not  adversely  affect  program  logic. 

Example: 

100  CLR 
CMD 

The  CMD  statement  sends  all  output  that  would  have  gone  to  the  display 
to  another  specified  unit.  Output  goes  to  that  unit,  instead  of  the  display,  until 
a  PRINT#  statement  specifying  the  same  logical  file  number  that  was  opened 
is  executed.  At  least  one  PRINT#  statement  must  follow  a  CMD  statement. 

Format: 


CMD// 
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The  CMD  statement  assigns  a  line  printer  output  channel  to  logical  file 
If.  After  execution  of  a  CMD  statement,  PRINT  and  LIST  both  print  data 
instead  of  displaying  it. 

Example: 


OPEN  5,4 

Open  logical  file  5  selecting  the  printer 

CMD  5 

Direct  subsequent  output  to  the  printer 

LIST 

Print  the  program  listing 

PRINT#5 

Print  a  carriage  return  and  deselect  the  printer 

CLOSE  5 

Close  logical  file  5 

COLLECT 

The  COLLECT  statement  recreates  a  Block  Availability  Map  (BAM)  for 
all  files  on  the  diskette.  Improperly  closed  files  are  closed  or  deleted. 

Format: 

COLLECT  [Dc/][ON  Vy] 

The  diskette  on  drive  d  is  collected.  If  the  Dd  parameter  is  absent,  drive  0 
is  assumed. 

Example: 

COLLECT  Collects  space  on  diskette  in  last  drive  accessed 

COLLECT  DO  Collects  space  on  diskette  in  drive  0 

COLLEC  T  Dl  Collects  space  on  diskette  in  drive  1 

COLLISION 

System  variable.  Detects  sprite-sprite  collisions  and  sprite-object  colli- 
sions on  the  screen.  There  are  two  options: 

0= Detect  sprite  to  sprite  collisions 

1  =  Detect  sprite  to  background  collisions 

Format: 

COLLISION  TJinett 

where  T  is  the  type  of  collision  to  detect  and  line#  is  the  line  you  want  to 
execute  if  a  collision  occurs. 
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COLOR 

Allows  you  to  specify  the  color  of  various  screen  objects. 

Format: 

COLOR  0,  C 

where  O  is  the  object  and  C  is  the  color.  The  options  for  O  are 

O=0:  Color  of  40-column  background 

0=  1 :  Color  of  40-column  foreground 

0=2:  Multi-color  #1 

0=3:  Multi-color  #2 

0=4:  Color  of  40-column  border 

0=5:  Character  color 

0=6:  Color  of  80-column  background 

The  color  options  in  40-column  mode  are 


1= 

BLACK 

2= 

WHITE 

3= 

RED 

4= 

CYAN 

5= 

PURPLE 

6= 

GREEN 

7= 

BLUE 

8= 

YELLOW 

9= 

ORANGE 

10= 

BROWN 

11  = 

LT  RED 

12= 

DARK  GRAY 

13= 

MED  GRAY 

14= 

LT  BLUE 

15= 

LT  GRAY 

The  color  options  in  80-column  mode  are 


1= 

BLACK 

2= 

WHITE 

3= 

DK  RED 

4= 

LT  CYAN 

5= 

LT  PURPLE 

6= 

DK  GREEN 

7= 

DK  BLUE 

8= 

LT  YELLOW 

9= 

DK  PURPLE 

10= 

DARK  YELLOW 

11  = 

LT  RED 

12= 

DARK  CYAN 

13= 

MED  GRAY 
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14=  LT  BLUE 
15=  LT  GRAY 

CONCAT 

The  CONCAT  statement  concatenates  two  data  files. 
Format: 

CONCAT[Ds]"sourcefile"  TO  [Dd,]"destfile"[ON  Uz] 

The  contents  of  sourcefile  on  the  diskette  in  drive  s  are  concatenated  onto 
the  end  of  destfile  on  the  diskette  in  drive  d.  The  file  named  sourcefile  does  not 
change.  The  file  named  destfile  keeps  its  original  contents,  with  the  contents 
of  sourcefile  tacked  on  at  the  end.  If  drive  numbers  s  and/ or  d  are  not 
specified,  then  drive  0  is  assumed. 

Caution:  Files  must  be  closed  before  they  are  concatenated. 

Example: 

CONCAT  "FIRST"  TO  "SECOND"  The  contents  of  file  FIRST  is  concatenated  on  the 

end  of  file  SECOND.  Both  files  are  on  the 
diskette  in  drive  0 

CONCAT  D 1  .•  "  ABC "  TO  D0 ,  "  X VZ "  The  contents  of  file  A  BC  on  the  diskette  in  drive  1 

is  concatenated  on  the  end  of  file  XYZ  on  the 
diskette  in  drive  0 

CONT 

The  CONT  statement,  typed  at  the  keyboard  in  immediate  mode, 
resumes  program  execution  after  a  BREAK. 

Format: 
CONT 

A  break  is  caused  by  execution  of  a  STOP  statement  or  an  END 
statement  that  has  additional  statements  following  it.  Depressing  the  STOP 
key  while  a  program  is  running  also  causes  a  break.  Program  execution 
continues  at  the  exact  point  where  the  break  occurred. 

Pressing  the  RETURN  key  in  response  to  an  INPUT  statement  will  also 
cause  a  break.  Typing  CONT  after  this  break  reexecutes  the  INPUT 
statement. 

Example: 
CONT 


BASIC  STATEMENTS  469 


COPY 

The  COPY  statement  copies  a  single  diskette  file,  or  all  the  files  on  a 
diskette. 

Format: 

COPY  \ps,Ysourcefile"]  TO  [Dd,]("destfile")[ON  Uz] 

If  the  COPY  statement  is  used  to  copy  a  single  file,  then  the  file  named 
sourcefile  on  the  diskette  on  drive  s  is  copied  to  a  new  file  named  destfile  on 
the  diskette  in  drive  d\  the  file  names  sourcefile  and  destfile  must  be  present, 
but  if  drive  numbers  s  and/ or  d  are  absent,  drive  0  is  assumed. 

The  COPY  statement  can  also  be  used  to  copy  all  files  from  the  diskette 
in  one  drive  to  the  diskette  in  the  other  drive.  To  use  the  COPY  statement  in 
this  fashion,  file  names  sourcefile  and  destfile  must  be  absent,  but  drive 
numbers  s  and  d  must  be  present  and  different. 

If  the  name  of  a  source  file  that  is  being  copied  exists  on  the  destination 
diskette,  then  the  copy  will  be  aborted  at  that  file,  and  a  FILE  ALREADY 
EXISTS  error  will  be  reported. 

COPY  does  not  modify  any  files  previously  on  the  destination  diskette. 

Caution:  A  file  must  be  closed  before  it  is  copied. 

Example: 

copy  ni  to  mi 

COPV  Dl,    "MAJOR"  TO  HI,  "MINOR" 

DATA 

The  DATA  statement  declares  constants  that  are  assigned  to  variables  by 
READ  statements. 

Format: 

DATA  constant[,constant , constant , . . .  ^constant] 

DATA  statements  may  be  placed  anywhere  in  a  program.  The  DATA 
statement  specifies  either  numeric  or  string  constants.  String  constants  are 
usually  enclosed  in  double  quotation  marks;  the  quotes  are  not  necessary 
unless  the  string  contains  graphics  characters,  blanks  (spaces),  commas,  or 
colons.  Blanks,  commas,  colons,  and  graphics  characters  are  ignored  unless 
the  string  is  enclosed  in  quotes.  A  double  quotation  mark  cannot  be  repre- 
sented in  a  DATA  string;  it  must  be  specified  using  a  CHR$(34)  function.  The 


Copy  all  files  on  the  diskette  in  drive  Dl  to  the 
diskette  in  drive  DO.  (DOS  2.0  and  higher 
releases  only) 

Create  MINOR  file  on  the  diskette  in  drive  Dl 
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DATA  statement  is  valid  in  program  mode  only. 
Example: 

10  DATA  NAME /'CD."      Defines  two  string  variables 

50  DATA  -10^  XVZ      Defines  two  numeric  variables  and  one  string 

variable 

Refer  to  the  READ  statement  for  a  description  of  how  DATA  statement 
constants  are  used  within  a  program. 

DCLEAR 

Closes  all  open  disk  channels  and  files  on  the  selected  device. 
Example: 

DCLEAR  DO 

Closes  all  the  files  and  open  channels  on  drive  0. 
DCLOSE 

DCLOSE  closes  a  single  file  or  all  the  files  currently  open  on  a  disk  unit. 
(Also  see  CLOSE.) 

Format: 

DCLOSE#//[ON  Uz] 

The  DCLOSE  statement  closes  logical  file  //  If  the  logical  file  number  is 
not  specified,  all  currently  open  diskette  files  are  closed. 

Example: 

DCLOSE  Closes  all  open  diskette  files 

DCLOSEtfl  Closes  the  diskette  file  identified  by  logical  file  1 

DCLOSE  ON  US       Closes  all  open  diskette  files  on  physical  unit  #8 

DEF  FN 

The  DEF  function  (DEF  FN)  allows  special-purpose  functions  to  be 
defined  and  used  within  BASIC  programs. 

Format: 

DEF  ¥Nnvar(arg)= expression 

Floating  point  variable  nvar  identifies  the  function,  which  is  subse- 
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quently  referenced  using  the  name  ¥Nnvar(data).  (If  nvar  has  more  than  five 
letters,  a  syntax  error  is  reported.  A  syntax  error  is  also  reported  if  nvar  is  a 
string  or  integer  variable.) 

The  function  is  specified  by  expression,  which  can  be  any  arithmetic 
expression  containing  any  combination  of  numeric  constants,  variables,  or 
operators.  The  dummy  variable  name  arg  can  (and  usually  does)  appear  in 
expression. 

The  arg  is  the  only  variable  in  expression  that  can  be  specified  when 
FNnvar  (data)  is  referenced.  Any  other  variables  in  expression  must  be  defined 
before  FNnvar(data)  is  referenced  for  the  first  time.  FNnvar(data)  evaluates 
expression  using  data  as  the  value  for  arg. 

The  entire  DEF  FN  statement  must  appear  on  a  single  80-character  line; 
however,  a  previously  defined  function  can  be  included  in  expression,  so 
user-defined  functions  of  any  complexity  can  be  developed. 

The  function  name  var  can  be  reused  and  therefore  redefined  by  another 
DEF  FN  statement  appearing  later  in  the  same  program. 

The  DEF  FN  definition  statement  is  illegal  in  immediate  mode.  How- 
ever, a  user-defined  function  that  has  been  defined  by  a  DEF  FN  statement  in 
the  current  stored  program  can  be  referenced  in  an  immediate  mode 
statement. 

Example: 

10  DEF  FNC<R)"ff#R12  Defines  a  function  that  calculates  the  circumfer- 

ence of  a  circle.  It  takes  a  single  argument  R, 
the  radius  of  the  circle,  and  returns  a  single 
numeric  value,  the  circumference  of  the 
circle 

?FNC  <  1 )  Prints  3. 141159265  (the  value  of  pi) 

35  IF  FNC(X)>60  00T0  150  Uses  the  value  calculated  by  the  user-defined  func- 
tion FNCas  a  branch  condition.  The  current 
contents  of  variable  X  are  used  when  calcu- 
lating the  user-defined  function 

DELETE 

Deletes  a  range  of  BASIC  lines  from  the  current  program.  The  options 

are 

DELETE  L# 
This  deletes  a  single  line  as  specified  by  L#. 
DELETE 

deletes  the  range  of  lines  between  the  two  L#'s. 
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DELETE  Lff- 
deletes  all  of  the  lines  that  follow  the  Lff. 

DELETE  -Lff 
deletes  all  of  the  line  prior  to  the  Lff. 

Example: 

DELETE   1000  -  2000 

will  delete  lines  1000  through  2000. 
DIM 

The  Dimension  statement  DIM  allocates  space  in  memory  for  array 
variables. 

Format: 

DIM  var(sub)[,var(sub),. .  .,var(sub)] 

The  DIM  statement  identifies  arrays  with  one  or  more  dimensions  as 
follows: 

var(sub[)  Single-dimensional  array 

var(subisubj)  Two-dimensional  array 

var(subisubjsub\,)     Multiple-dimensional  array 

Arrays  with  more  than  11  elements  must  be  dimensioned  in  a  DIM 
statement.  Arrays  with  11  elements  or  less  (subscripts  0  through  10  for  a 
one-dimensional  array)  may  be  used  without  being  dimensioned  by  a  DIM 
statement;  for  such  arrays,  11  array  spaces  are  automatically  allocated  in 
memory  when  the  first  array  element  is  encountered  in  the  program.  An  array 
with  more  than  11  elements  must  occur  in  a  DIM  statement  before  any  other 
statement  references  an  element  of  the  array. 

If  an  array  is  dimensioned  more  than  once,  or  if  an  array  having  more 
than  11  elements  is  not  dimensioned,  an  error  occurs  and  the  program  is 
aborted.  A  CLR  statement  allows  a  DIM  statement  to  be  reexecuted. 

Example: 

10  DIM  fl(3)  Dimension  a  single-dimensional  array  of 3  elements 

43  DIM  X$  (.  44 1 2  )  Dimension  a  two-dimensional  array  of  88  elements 

1000  DIM  MU<X;3#B)^N(12)  Dimension  a  two-dimensional  array  of  X  times 

3*B  elements  and  a  single-dimensional  array 
of  12  elements.  X  and  B  must  have  been 
assigned  values  before  the  DIM  statement  is 
executed 
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DIRECTORY 

The  DIRECTORY  statement  displays  directories  for  diskettes  in  one  or 
both  drives.  The  word  CATALOG  may  be  used  instead  of  DIRECTORY. 

Format: 

Dl  RECTORY[Dd][ON  Uz] 

The  directory  for  the  diskette  in  drive  d  is  displayed.  If  the  Dd  parameter 
is  absent,  directories  for  the  diskettes  in  both  drives  are  displayed. 

If  a  selected  drive  contains  no  diskette  an  error  status  is  reported. 
The  DIRECTORY  statement  is  usually  executed  in  immediate  mode. 

Example: 

Ii  I  RECTORV  Displays  the  directory  of  drive  0  and  drive  1 

D I RECTORV  Dl       Displays  the  directory  of  drive  1 


Printing  a  Directory 

A  directory  can  be  printed  instead  of  being  displayed  by  opening  a  printer 
channel  before  executing  the  DIRECTORY  statement.  Here  is  the  required 
immediate  mode  statement  sequence: 


OPEN  4 ,  4  Open  the  printer  specifying  logical  file  4 

CMIi  4  Deflect  display  output  to  the  printer 

B I  RECTORV  Print  directories  for  diskettes  in  both  drives 

-RINT#4  Deflect  output  back  to  the  display 
CLOSE  4 


DLOAD 

The  DLOAD  statement  loads  a  BASIC  program  from  a  diskette  into 
memory  (also  see  LOAD). 

Format: 

DLOAD  "filename"[Dd][ON  Uz] 

The  DLOAD  statement  loads  program  file  filename  from  the  diskette  in 
drive  d  into  computer  memory.  If  d  is  not  present,  drive  0  is  assumed. 
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Example: 

DLOflD  "CRLC"  Load  CALCfile  from  drive  0 

DLOflD  "  T I  ME " ,  D 1  Load  TIME  file  from  drive  1 

fl*=,,PR0G"  Load  PROG  file  from  drive  0 
DLOflD  fl$ 

DLOflD  "PROG" ,  D6  ON  US  Load  PROG  file  from  drive  0  on  the  disk  unit 

Using  BASIC  4.0,  if  you  press  the  shifted  RUN/ STOP  key,  the  next 
program  encountered  on  the  diskette  is  loaded  and  run. 


DOPEN 

DOPEN  opens  a  data  file  for  a  read  and/or  write  access. 
Format: 

DOPEmiffufllenamen[,Ly]lDd][GN  Uz][,  W] 

The  DOPEN  statement  opens  data  file  filename  on  the  diskette  in  drive 
d,  assigning  to  it  logical  file  number  If.  If  d  is  not  specified  then  drive  0  is 
assumed.  If  Ly  is  not  present  then  a  sequential  file  is  assumed.  The  sequential 
file  is  opened  for  a  write  access  if  W\s  not  present;  it  is  opened  for  a  read  access 
if  W  is  present. 

If  Ly  is  present  then  a  relative  file  is  assumed  with  a  record  length  of  y 
bytes.  Relative  files  are  opened  for  read  or  write  accesses;  therefore  the  W 
parameter  cannot  be  present. 

Example: 

Opens  the  sequential  file  named  PRIZES  on  drive 

0  for  a  read  access 
Opens  the  relative  file  named  SNAKE,  with  a 
record  length  of  30,  for  read  and  write 
accesses.  The  file  is  on  drive  Dl 

DRAW 

Draws  a  line  on  the  graphics  screen. 

Format: 

DRAW  C,  XA,  YA  TO  XB,  YB 

where  Cis  the  color  of  the  line,  XA  and  YA  specify  one  end  of  the  line,  and  XB 
and  YB  specify  the  other  end  of  the  line. 


D0PEN# 1, "PRIZES" 
D0PEN#6,  " SNAKE "L 38..  Dl 
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Options: 

DRAW  C,  XA,  YA  TO  XB,  YB  TO  XC,  YC. . . 

In  this  case,  a  continuous  line  is  drawn  between  the  points  specified  by  each  X 
and  Y  pair. 

DSAVE 

The  DSAVE  statement  writes  a  BASIC  program  file  from  memory  onto 
a  diskette  (also  see  SAVE). 

Format: 

DSAVE"/?/^flw^"[,DJ][ON  Uz] 

The  DSAVE  statement  saves  the  BASIC  program  currently  in  memory, 
writing  it  to  a  new  file  named  filename,  on  the  diskette  in  drive  d.  If  d  is  not 
present,  drive  0  is  assumed. 

Example: 

DSflVE "  TRUE "  Write  program  file  TRUE  to  diskette  in  drive  0 

PSfiVE "  FALSE " ,  PI  Write  program  file  FALSE  to  diskette  in  drive  1 

END 

The  END  statement  terminates  program  execution  and  returns  the 
computer  to  immediate  mode. 

Format: 
END 

The  END  statement  can  provide  a  program  with  one  or  more  termina- 
tion points  at  locations  other  than  the  physical  end  of  the  program.  END 
statements  can  be  used  to  terminate  individual  programs  when  more  than  one 
program  is  in  memory  at  the  same  time.  An  END  statement  at  the  physical 
end  of  the  program  is  optional.  The  END  statement  is  used  in  program  mode 
only. 

Example: 

28001  END 


ENVELOPE 

Specifies  a  set  of  sound  parameters  for  the  PLAY  command. 
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Format: 

ENVELOPE  N,A,D,S,R,  W,P 

where  TV  is  the  envelope  number  (0-9),  A  is  the  attack  value  (0-15),  D  is  the 
decay  value  (0-15),  S  is  the  sustain  value  (0-15),  R  is  the  release  value  (0-15), 
W  is  the  waveform  number  (0-4),  and  P  is  the  pulse  width  (0-4095). 

EXIT 

Leaves  the  monitor  and  returns  to  BASIC. 

Format: 
EXIT 

FAST 

Switches  the  computer  from  slow  mode  (1  Mhz)  to  fast  mode  (2  Mhz). 
Does  not  work  properly  with  I/O  functions  or  graphics. 

Format: 
FAST 

FETCH 

Gets  a  range  of  data  from  the  expansion  RAM. 

Format: 

FETCH  B,  SI,  Rtt,  SX 

where  B  is  the  number  of  bytes  you  want  to  read,  57is  the  starting  number  of 
internal  RAM  you  want  to  write,  Rtt  is  the  RAM  bank  you  want  to  read  from, 
and  SX  is  the  starting  address  of  the  expansion  RAM. 

FILTER 

Specifies  a  set  of  filter  parameters  for  the  SID  chip. 

Format: 

FILTER  F,  L,  B,  H,  R 

where  Fis  the  cut-off  frequency,  L  selects  the  low  pass  filter,  B  selects  the  band 
pass  filter,  H  selects  the  high  pass  filter,  and  R  selects  resonance. 

FOR-NEXT  STEP 

All  statements  between  the  FOR  statement  and  the  NEXT  statement  are 
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reexecuted  the  same  number  of  times. 


Format: 


FOR  nvar  =  start  TO  end  STEP  increment 

[statements  in  loop] 

NEXT[nvar] 

where  the  variables  are  defined  as  follows: 

nvar  is  the  index  of  the  loop.  It  holds  the  current  loop  count.  The 

nvar  is  often  used  by  the  statements  within  the  loop. 

start  is  a  numeric  constant,  variable,  or  expression  that  specifies 

the  beginning  value  of  the  index. 

end  is  a  numeric  constant,  variable,  or  expression  that  specifies 

the  ending  value  of  the  index.  The  loop  is  completed  when 
the  index  value  is  equal  to  the  end  value,  or  when  the  index 
value  is  incremented  or  decremented  past  the  end  value. 

increment  if  present,  is  a  numeric  constant,  variable,  or  expression  that 
specifies  the  amount  by  which  the  index  variable  is  to  be 
incremented  with  each  pass.  The  step  may  be  incremental 
(positive)  or  decremental  (negative).  If  STEP  is  omitted,  the 
increment  defaults  to  1 . 

The  nvar  may  optionally  be  included  in  the  NEXT  statement.  A  single 
NEXT  statement  is  permissible  for  nested  loops  that  end  at  the  same  point. 
The  NEXT  statement  then  takes  the  form 

NEXT  nvari,nvar2. . . 

The  FOR-NEXT  loop  will  always  be  executed  at  least  once,  even  if  the 
beginning  nvar  value  is  beyond  the  end  nvar  value.  If  the  NEXT  statement  is 
omitted  and  no  subsequent  NEXT  statements  are  found,  the  loop  is  executed 
once. 

The  start,  end,  and  increment  values  are  read  only  once,  on  the  first 
execution  of  the  FOR  statement.  You  cannot  change  these  values  inside  the 
loop.  You  can  change  the  value  of  nvar  within  the  loop.  This  may  be  used  to 
terminate  a  FOR-NEXT  loop  before  the  end  value  is  reached:  Set  nvar  to  the 
end  value  and  on  the  next  pass  the  loop  will  terminate  itself.  Do  not  jump  out 
of  the  FOR-NEXT  loop  with  a  GOTO.  Do  not  start  the  loop  outside  a 
subroutine  and  terminate  it  inside  the  subroutine. 

FOR-NEXT  loops  may  be  nested.  Each  nested  loop  must  have  a  differ- 
ent nvar  variable  name.  Each  nested  loop  must  be  wholly  contained  within 
the  next  outer  loop;  at  most,  the  loops  can  end  at  the  same  point. 
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GET 

The  GET  statement  receives  single  characters  as  input  from  the 
keyboard. 

Format: 

GET  var 

The  GET  statement  can  be  executed  in  program  mode  only.  When  a 
GET  statement  is  executed,  var  is  assigned  a  0  value  if  numeric  or  a  null  value 
if  a  string.  Any  previous  value  of  the  variable  is  lost.  Then  GET  fetches  the 
next  character  from  the  keyboard  buffer  and  assigns  it  to  var.  If  the  keyboard 
buffer  is  empty,  var  retains  its  0  or  null  value. 

GET  is  used  to  handle  one-character  responses  from  the  keyboard.  GET 
accepts  the  RETURN  key  as  input  and  passes  the  value  (CHR$(13))  to  var. 

If  var  is  a  numeric  variable  and  no  key  has  been  pressed,  0  is  returned. 
However,  a  0  is  also  returned  when  0  is  entered  at  the  keyboard. 

If  var  is  a  numeric  variable  and  the  character  returned  is  not  a  digit  (0-9), 
a  7SYNTAX  ERROR  message  is  generated  and  the  program  aborts. 

The  GET  statement  may  have  more  than  one  variable  in  its  parameter 
list,  but  it  is  hard  to  use  if  it  has  multiple  parameters. 

GET  var, var, .  . .  ,var 

Example: 

10  GET  C$ 

18  GET  D 

10  GET  R,B,C 

GETKEY 

Gets  a  keystroke  from  the  keyboard.  The  difference  between  GETKEY 
and  GET  is  that  GETKEY  makes  the  computer  pause  while  it  waits  for  entry 
and  GET  does  not.  The  following  lines  would  be  identical  in  operation: 

10  GET  A*:    IF  A$=,,n   THEN  GOTO  10 
10  GETKEY  A* 

GET# 

The  GET  External  statement  (GET#)  receives  single  characters  as  input 
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from  an  external  storage  device  identified  via  a  logical  file  number. 

Format: 

GET#//,var 

The  GET#  statement  can  only  be  used  in  program  mode.  GET#  fetches  a 
single  character  from  an  external  device  and  assigns  this  character  to  variable 
var.  The  external  device  is  identified  by  logical  file  number  If.  This  logical  file 
must  have  been  previously  opened  by  an  OPEN  statement. 

GET#  and  GET  statements  handle  variables  and  data  input  identically. 
For  details  see  the  GET  statement  description. 

Example: 

10  GET#4>C$:IF  C$9""  GOTO  10         Get  a  keyboard  character.  Reexecute  if no  charac- 
ter is  present 

G064 

Switches  the  C-128  to  C-64  mode. 

Format: 
G064 

GOSUB 

The  GOSUB  statement  branches  program  execution  to  a  specified  line 
and  allows  a  return  to  the  statement  following  GOSUB.  The  specified  line  is  a 
subroutine  entry  point. 

Format: 

GOSUB  In 

The  GOSUB  statement  calls  a  subroutine.  The  subroutine's  entry  point 
must  occur  on  line  In.  A  subroutine's  entry  point  is  the  beginning  of  the 
subroutine  in  a  programming  sense;  that  is  to  say,  it  is  the  line  containing  the 
statement  (or  statements)  that  are  executed  first.  The  entry  point  need  not 
necessarily  be  the  subroutine  line  with  the  smallest  line  number. 

Upon  completing  execution  the  subroutine  branches  back  to  the  line 
following  the  GOSUB  statement.  The  subroutine  uses  a  RETURN  statement 
in  order  to  branch  back  in  this  fashion. 

A  GOSUB  statement  may  occur  anywhere  in  a  program;  in  consequence 
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a  subroutine  may  be  called  from  anywhere  in  the  program. 


Example: 


100  GOSUB  2080 
110  fl*B*C 


Branch  to  subroutine  at  line  2000 
Subroutine  branches  back  here 


2000 


Subroutine  entry  point 


2090  RETURN 


Branch  back  to  line  110 


GOTO 


The  GOTO  statement  branches  unconditionally  to  a  specified  line. 


GOTO  In 

Example: 

10  GOTO  100 

Executed  in  immediate  mode,  GOTO  branches  to  the  specified  line  in  the 
stored  program  without  clearing  the  current  variable  values.  GOTO  cannot 
reference  immediate  mode  statements,  since  they  do  not  have  line  numbers. 


Selects  one  of  the  graphics  modes  of  the  C-128.  The  options  are: 

0=40-column  text 
1  =  bit-mapped  graphics 
2=  split-screen  graphics /text 
3= multi-color  graphics 
4=  multi-color  split 
5=80-column  text 


The  HEADER  statement  formats  a  diskette,  assigning  it  a  disk  name 
and  identification  number. 


Format: 


GRAPHIC 


HEADER 
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Format: 

HEADER  "diskname",r>d[Jvv][ON  Uz] 

When  formatting  a  diskette  the  HEADER  statement  marks  off  sectors 
on  each  track,  then  initializes  the  directory  and  Block  Availability  Map.  The 
formatted  diskette  must  be  in  drive  d.  The  diskette  is  given  the  name  disk- 
name  and  the  number  vv.  This  name  and  number  appears  in  the  reverse  field 
at  the  top  of  a  diskette  directory  display. 

The  HEADER  statement  is  usually  executed  in  immediate  mode. 

The  HEADER  statement  can  be  used  to  format  a  blank  diskette  or  to 
reformat  and  clear  a  used  diskette.  Because  the  changes  are  permanent,  this 
command  requires  caution  in  its  use.  If  executed  in  immediate  mode,  the 
question  ARE  YOU  SURE?  is  displayed.  You  must  respond  by  typing  YES  to 
continue. 

If  a  media  error  occurs  when  the  HEADER  statement  is  executed,  a 
?BAD  DISK  message  is  displayed  on  the  screen.  Media  errors  occur  when  a 
diskette  is  missing  from  the  drive,  the  write-protect  tab  is  in  place,  or  the 
diskette  magnetic  surface  is  defective. 

Example: 

HEhBER  "  MASTER "  .■  BG ,  1 02         Prepare  and  format  a  diskette,  giving  it  the  name 

"MA S TER  "and  the  number  02.  The  diskette 
is  in  drive  0 

HELP 

This  is  a  debugging  tool.  When  HELP  is  activated,  any  error  will  be 
listed  and  displayed  in  reverse  characters  on  the  screen. 

IF-THEN 

The  IF-THEN  statement  provides  conditional  execution  of  statements 
based  on  a  relational  expression. 

Format: 

IF  condition  THEN  statement[:statement . . .]  Conditionally  execute  statement(s) 


IF  condition 


Conditionally  branch 


If  the  specified  condition  is  true,  then  the  statement  or  statements 
following  the  THEN  are  executed.  If  the  specified  condition  is  false,  control 
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passes  to  the  statement(s)  on  the  next  line  and  the  statement  or  statements 
following  the  THEN  are  not  executed.  For  a  conditional  branch,  the  branch 
line  number  is  placed  after  the  word  THEN  or  after  the  word  GOTO.  The 
compound  form  THEN  GOTO  is  also  acceptable. 

IF  A  =  1  THEN  50  ) 

IF  A  =  1  GOTO  50  /  Equivalent 

IF  A  =  1  THEN  GOTO  50  ) 

If  an  unconditional  branch  is  one  of  many  statements  following  THEN, 
the  branch  must  be  the  last  statement  on  the  line,  and  it  must  have  "GOTO 
line"  format.  If  the  unconditional  branch  is  not  the  last  statement  on  the  line, 
then  statements  following  the  unconditional  branch  can  never  be  executed. 

The  following  statements  cannot  appear  in  an  immedate  mode  IF-THEN 
statement:  DATA,  GET,  GET#,  INPUT,  INPUT#,  REM,  RETURN,  END, 
STOP,  WAIT. 

If  a  line  number  is  specified,  or  any  statement  containing  a  line  number, 
there  must  be  a  corresponding  statement  with  that  line  number  in  the  current 
stored  program. 

The  CONT  and  DATA  statements  cannot  appear  in  a  program  mode 
IF-THEN  statement.  If  a  FOR-NEXT  loop  follows  the  THEN,  the  loop  must 
be  completely  contained  on  the  IF-THEN  line.  Additional  IF-THEN  state- 
ments may  appear  following  the  THEN  as  long  as  they  are  completely 
contained  on  the  original  IF-THEN  line.  However,  Boolean  connectors  are 
preferred  to  nested  IF-THEN  statements.  For  example,  the  two  statements 
below  are  equivalent,  but  the  second  is  preferred. 

10  IF  fl*-"X"  THEN  IF  B»2  THEN  IF  OD  THEN  50 
10  IF  R*-"XH  AND  B«2  AND  OD  THEN  50 

Example: 

400  IF  X>V  THEN  A*l 

500  IF  M+l  THEN  AG«4.5  GOSUB  1000 

INITIALIZE 

You  can  use  PRINT#  to  inititialize  a  diskette  before  performing  any 
operation  on  it. 

Format: 

PRINT#/?/e,"[INITIALIZE][^/r],, 

The  diskette  in  drive  dr  is  initialized.  If  the  dr  parameter  is  not  present, 
the  diskette  in  drive  0  will  be  initialized.  You  do  not  need  to  initialize  a  diskette 
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after  preparing  it;  the  preparation  process  also  initializes  the  diskette. 


Example: 


OPEN  1,8,15 


Open  the  diskette  command  channel 


PRINT#1,'»I" 


Initialize  diskettes  in  drive  0 


INPUT 

The  INPUT  statement  receives  data  input  from  the  keyboard. 


Format: 


INPUT 


f  (blank)  ) 
\  "message  " ;  J 


var[,var, . . .  ,var] 


INPUT  can  be  used  in  program  mode  only.  When  the  INPUT  statement 
is  executed,  C-128  BASIC  displays  a  question  mark  on  the  screen  requesting 
data  input.  The  user  must  enter  data  items  that  agree  exactly  in  number  and 
type  with  the  variables  in  the  INPUT  statement  parameter  list.  If  the  INPUT 
statement  has  more  than  one  variable  in  its  parameter  list,  then  keyboard 
entries  must  be  separated  by  commas.  The  last  entry  must  be  terminated  with 
a  carriage  return. 


?1234<CR> 

?1234,567.89,NOW<CR> 


Single  data  item  response 
Multiple  data  item  response 


If  message  is  present,  it  is  displayed  before  the  question  mark.  A  message 
can  have  as  many  as  80  characters. 

If  more  than  one  but  fewer  than  the  required  number  of  data  items  are 
input,  C-128  BASIC  requests  additional  input  with  double  question  marks 
(??)  until  the  required  number  of  data  items  have  been  input.  If  too  many  data 
items  are  input,  the  message  7EXTRA  IGNORED  is  displayed.  The  extra 
input  is  ignored,  but  the  program  continues  execution. 


Example: 


Statement 

10  INPUT  fl,B,C* 

10  INPUT  fl,B,C$ 

10  INPUT  fl,B,C$ 


Operator  Response 

?  123, 456, NOW 

?  123 
??  456 

??  NOW 

?  NOW 


Result 

A=123,  B=456,  C$="NOW" 

A=123 
B=456 
C$="NOW" 
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7RED0  FROM  START 
?  123 
??  456 
??  789 

10  INPUT  "A«  fl»  ?  123 


A=123 
B=456 
C-789 

A=123 


Note  that  you  must  input  numeric  data  for  a  numeric  variable,  but  you 
can  input  numeric  or  string  data  for  a  string  variable. 

INPUT* 

The  INPUT  External  statement  (INPUT#)  inputs  one  or  more  data 
items  from  an  external  device  identified  via  a  logical  file  number. 

Format: 

INPUT#// w[,var,. . .  ,var] 

The  INPUT#  statement  inputs  data  from  the  selected  external  device 
and  assigns  data  items  to  variable(s)  var.  Data  items  must  agree  in  number 
and  kind  with  the  INPUT#  statement  parameter  list. 

If  an  end-of-record  is  detected  before  all  variables  in  the  INPUT# 
statement  parameter  list  have  received  data,  then  an  OUT  OF  DATA  error 
status  is  generated,  but  the  program  continues  to  execute. 

INPUT#  and  INPUT  statements  execute  identically,  except  that  INPUT# 
receives  its  input  from  a  logical  file.  Also,  INPUTS  does  not  display  error 
messages;  instead,  it  reports  error  statuses  that  the  program  must  interrogate 
and  respond  to. 

Input  data  strings  may  not  be  longer  than  80  characters  (79  characters 
plus  a  carriage  return)  because  the  input  buffer  has  a  maximum  capacity  of  80 
characters.  Commas  and  carriage  returns  are  treated  as  item  separators  by  the 
computer  when  processing  the  INPUTS  statement;  they  are  recognized,  but 
are  not  passed  on  to  the  program  as  data.  INPUTS  is  valid  in  program  mode 
only. 

Example: 

1000  INPUT#10> fi        Input  the  next  data  item  from  logical  file  10.  A 

numeric  data  item  is  expected;  it  is  assigned  to  variable  A 

946  INPUT#12;R$        Input  the  next  data  item  from  logical  file  12.  A 

string  data  item  is  expected;  it  is  assigned  to  variable  A$. 

900  INPUT#5;  B;  CI      Input  the  next  two  data  items  from  logical  file  5. 

The  first  data  item  is  numeric;  it  is  assigned  to  numeric 
variable  B.  The  second  data  item  is  a  string;  it  is 
assigned  to  string  variable  C$. 
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KEY 


Displays  the  current  commands  stored  in  the  function  keys. 


Format: 


KEY 


lfT= 


The  Assignment  statement  LET=,  or  simply  =,  assigns  a  value  to  a 
specified  variable. 


Variable  var  is  assigned  the  value  computed  by  resolving  data.  The  word 
LET  is  optional;  it  is  usually  omitted. 

Example: 

18  A*2 
450  C*»M*n 

300  M(1,3)«80N<X> 

310  XX$<LJ,K,l>«MSTRINGflLONGu 


LIST  displays  one  or  more  lines  of  a  program.  Program  lines  displayed 
by  the  LIST  statement  may  be  edited. 


Format: 


LIST 


Format: 


LIST 


(blank) 


line \— line 2 


The  entire  program  is  displayed  in  response  to  LIST.  Use  line-limiting 
parameters  for  long  programs  to  display  a  section  of  the  program  that  is  short 
enough  to  fit  on  the  screen. 
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Example: 


LIST 


List  entire  program 


LIST  50 


List  line  50 


LIST  60-100 


List  all  lines  in  the  program  from  lines  60  to  100, 
inclusive 


LIST  -140 


List  all  lines  in  the  program  from  the  beginning  of 
the  program  through  line  140 


LIST  20000- 


List  all  lines  in  the  program  from  line  20000  to  the 
end  of  the  program 


Listed  lines  are  reformatted  as  follows: 

1.  ?'s  entered  as  a  shorthand  for  PRINT  are  expanded  to  the  word 
PRINT.  Example: 

?A  becomes  PRINT  A 

2.  Blanks  preceding  the  line  number  are  eliminated.  Example: 
50A=1  50A=1 


3.  A  space  is  inserted  between  the  line  number  and  the  rest  of  the 
statement  if  none  was  entered.  Example: 

55A=B-2  becomes  55  A=B~2 

LIST  is  always  used  in  immediate  mode.  A  LIST  statement  in  a  program 
will  list  the  program  but  then  exit  to  immediate  mode.  Attempting  to  con- 
tinue program  execution  via  CONT  simply  repeats  the  LIST  indefinitely. 

Printing  a  Program  Listing 

To  print  a  program  listing  instead  of  displaying  it,  OPEN  a  printer 
logical  file  and  execute  a  CMD  statement  before  executing  the  LIST  state- 
ment. Here  is  the  necessary  immediate  mode  sequence: 

OPEN  4*4  Open  the  printer  specifying  logical  file  4 

CMD  4  Deflect  display  output  to  the  printer 

LIST  Print  the  program  listing 

PRINT#4  Deflect  output  back  to  the  display 


The  LOAD  statement  loads  a  program  from  an  external  device  into 
memory. 


becomes 
100  A=A+1 


100  A=A+1 


CLOSE  4 


LOAD 
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Cassette  Program  Format 

LOAD  ["filename"]ldev] 

The  LOAD  statement  loads  into  memory  the  program  file  specified  by 
filename  from  the  cassette  unit  selected  by  device  number  dev.  If  no  device  is 
specified,  device  1  is  assumed  by  default;  cassette  unit  1  is  then  selected.  If  no 
file  name  is  given,  the  next  file  detected  on  the  selected  cassette  unit  is  loaded 
into  memory. 


Example: 
LORD 


LORD  "%2 
LORD  "EGOR" 


N**"WHEE!L8" 
LORD  N* 

LORD  "X" 


Load  into  memory  the  next  program  found  on 
cassette  unit  #1.  If  you  start  a  LOAD  when 
the  cassette  is  in  the  middle  of  a  program,  the 
cassette  will  read  past  the  remainder  of  the 
current  program,  then  load  the  next  program 

Load  into  memory  the  next  program  found  on 
cassette  unit  #2 

Search  for  the  program  named  EG  OR  on  tape 
cassette  #1  and  load  it  into  memory 

Search  for  the  program  named  WHEEILS  on 
cassette  unit  #1  and  load  it  into  memory 

Search  for  a  program  named  X  on  cassette  unit  #1 
and  load  it  into  memory 


Diskette  Drive  Program  Format 

LOAD  "dr:filename",dev 

The  LOAD  statement  loads  into  computer  memory  the  program  file 
with  the  filename  on  the  diskette  in  drive  dev.  The  device  number  for  the 
diskette  drive  unit  is  8  in  the  C-128.  If  dev  is  not  present,  the  default  value  is  1 , 
which  selects  the  primary  tape  cassette  unit. 

A  single  asterisk  can  be  included  instead  of  the  file  name,  in  which  case 
the  first  program  found  on  the  selected  diskette  drive  is  loaded  into  memory. 


Example: 

LORDM0:*%8 

LORD "8 ; FIREBALL" *  8 

T*»"0: METEOR" 
LORD  T$,8 


Load  the  first  program  found  on  disk  drive  0 

Search  for  the  program  named  FIREBALL  on  disk 
drive  0  and  load  it  into  memory 

Search  for  the  program  named  METEOR  on  disk 
drive  0  and  load  it  into  memory 
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When  a  LOAD  is  executed  in  immediate  mode,  C-128  BASIC  automati- 
cally executes  CLR  before  the  program  is  loaded.  Once  a  program  has  been 
loaded  into  memory,  it  can  be  listed,  updated,  or  executed. 

The  LOAD  statement  can  also  be  used  in  program  mode  to  build 
program  overlays.  A  LOAD  statement  executed  from  within  a  program 
causes  that  program's  execution  to  stop  and  another  program  to  be  loaded.  In 
this  case  the  C-128  computer  does  not  perform  a  CLR;  therefore,  the  old 
program  can  pass  on  all  of  its  variable  values  to  the  new  program. 

When  a  LOAD  statement  accesssing  a  cassette  unit  is  executed  in 
program  mode,  LOAD  message  displays  are  suppressed  unless  the  tape  PLAY 
key  is  up  (OFF).  If  the  PLAY  key  is  OFF,  the  PRESS  PLAY  ON  TAPE  #1 
message  is  displayed  so  that  the  load  can  proceed.  All  LOAD  messages  are 
suppressed  when  programs  are  loaded  from  a  diskette  in  program  mode. 

LOCATE 

Positions  the  pixel  cursor  in  the  specified  location  on  the  graphics 
screen. 

Format: 

LOCATE  X,  Y 

where  X  and  Y  are  the  new  x  and  y  coordinates  of  the  pixel  cursor. 

MONITOR 

Enters  the  machine  language  monitor. 

Format: 

MONITOR 

MOVSPR 

This  command  is  used  to  either  position  a  sprite  on  the  screen  or  to 
specify  a  direction  and  speed  for  sprite  movement. 

Format: 

MOVSPR  S,  X,  Y 

where  S  is  the  sprite  number,  and  ^and  7 specify  the  location  on  the  screen. 
Or 

movspr  x,  a,  nsp 

where  X  is  the  sprite  number,  A  is  the  angle  of  movement,  and  SP  is  the  speed 
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of  the  sprite  (0-15).  NOTE:  The  #  sign  is  necessary. 
NEW 

The  NEW  statement  clears  the  current  program  from  memory. 

Format: 
NEW 

When  a  NEW  statement  is  executed,  all  variables  are  initialized  to  zero 
or  null  values  and  array  variable  space  in  memory  is  released.  The  pointers 
that  keep  track  of  program  statements  are  reinitialized,  which  has  the  effect  of 
deleting  any  program  in  memory;  in  fact  the  program  is  not  physically 
deleted.  NEW  operations  are  automatically  performed  when  a  LOAD  state- 
ment is  executed. 

If  there  is  a  program  in  memory,  you  should  execute  a  NEW  statement  in 
immediate  mode  before  entering  a  new  program  at  the  keyboard.  Otherwise, 
the  new  program  will  overlay  the  old  one,  replacing  lines  if  their  numbers  are 
duplicated,  but  leaving  other  lines.  The  result  is  a  scrambled  mixture  of  two 
unrelated  programs. 

Example: 
NEW 

NEW  is  always  executed  in  immediate  mode.  If  a  NEW  statement  is 
executed  from  within  a  program,  the  program  will  "self-destruct,"  or  clear 
itself  out. 

NEW  (DOS  Command) 

Use  PRINT#  to  prepare  and  format  a  new  diskette  or  to  erase  and 
reformat  an  old  diskette. 

Format: 

PRINT#//,"N[EW]^wA:  name,vv" 

The  diskette  in  drive  dr  is  prepared.  When  a  diskette  is  prepared,  sectors 
are  laid  out  on  the  diskette  surface.  The  diskette  directory  and  Block  Availa- 
bility Map  (BAM)  are  initialized.  The  diskette  is  assigned  the  name  disk  name 
and  the  number  vv. 

The  diskette  name  and  number  are  displayed  in  the  reverse  field  at  the 
top  of  a  directory  display. 
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Example: 

OPEN  1,8,15  Open  the  diskette  command  channel 

PR  INT#1,  "  NO  :  NEWDflTR  ,  02  "         A  diskette  has  been  prepared for  use  in  drive  0.  The 

diskette  is  given  the  name  NEWDATA  and 
the  number  02 

ON-GOSUB 

The  ON-GOSUB  statement  provides  conditional  subroutine  calls  to  one 
of  several  subroutines  in  a  program,  depending  on  the  current  value  of  a 
variable. 

Format: 

ON  byte  GOSUB  lmei[Jine2,.  ..Jinen] 

ON-GOSUB  has  the  same  format  as  ON-GOTO.  Refer  to  the  ON-GOTO 
statement  description  for  branching  rules.  The  byte  is  evaluated  and  trun- 
cated to  an  integer  number,  if  necessary. 

For  byte=l9  the  subroutine  beginning  at  linei  is  called.  That  subroutine 
completes  execution  with  a  RETURN  statement  that  causes  program  execu- 
tion to  continue  at  the  statement  immediately  following  ON-GOSUB.  If 
byte— :2,  the  subroutine  beginning  with  Une2  is  called,  and  so  on. 

ON-GOSUB  is  normally  executed  in  program  mode.  It  may  be  executed 
in  immediate  mode  as  long  as  there  are  corresponding  line  numbers  to  branch 
to  in  the  current  stored  program. 

Example: 

10  ON  R  GOSUB  180,200,300 

ON-GOTO 

The  ON-GOTO  statement  causes  a  conditional  branch  to  one  of  several 
points  in  a  program,  depending  on  the  current  value  of  a  variable. 

Format: 

ON  byte  GOTO  linei[Jine^. . .  Jinen] 

byte  is  evaluated  and  truncated  to  an  integer  number,  if  necessary. 

If  byte=l,  a  branch  to  line  number  linex  occurs.  If  byte— :2,  a  branch  to 


BASIC  STATEMENTS  491 


line  number  line?,  occurs,  and  so  on. 

If  byte=0,  no  branch  is  taken.  If  byte  is  in  the  allowed  range  but  there  is 
no  corresponding  line  number  in  the  program,  then  no  branch  is  taken.  If  a 
branch  is  not  taken,  program  control  proceeds  to  the  statement  following  the 
ON-GOTO;  this  statement  may  be  on  the  same  line  as  the  ON-GOTO 
(separated  by  a  colon)  or  on  the  next  line. 

If  index  has  a  nonzero  value  outside  of  the  allowed  range,  the  program 
aborts  with  an  error  message.  As  many  line  numbers  may  be  specified  as  will 
fit  on  the  80-character  line. 

ON-GOTO  is  normally  executed  in  program  mode.  It  may  be  executed  in 
immediate  mode  as  long  as  there  are  corresponding  line  numbers  in  the 
current  stored  program  that  may  be  branched  to. 

Example: 


40  fl^B^  10  Branch  to  statement  100  if  A  is  true  (-l)or  branch 

50  ON  fl+2  GOTO  100.200  to  statement  200  if  A  is  false  (0) 

50  X=X+1  Branch  to  statement  500  ifX=l,  statement  600  if 

60  ON  X  GOTO  500.600.700  X=2,  or  to  statement  700  if  X=3.  No  branch 

is  taken  if  X>3 


OPEN 

The  OPEN  statement  opens  a  logical  file  and  readies  the  assigned 
physical  device. 

Cassette  Data  File  Format 

OPEN  IJl.dev^sd^rfilename^ 

The  file  named  filename  on  the  tape  cassette  unit  identified  by  dev  is 
opened  for  the  type  of  access  specified  by  the  secondary  address  sa\  the  access 
is  assigned  the  logical  file  number  If. 

If  no  file  name  is  specified,  the  next  file  encountered  on  the  selected  tape 
cassette  is  opened.  If  no  device  is  specified,  device  number  1  is  selected  by 
default;  this  device  number  selects  cassette  unit  1 .  If  no  secondary  address  is 
specified,  a  default  value  of  0  is  assumed  and  the  file  is  opened  for  a  read 
access  only.  A  secondary  address  of  1  opens  the  file  for  a  write  access,  while  a 
secondary  address  of  2  opens  the  file  for  a  write  access  with  an  end-of-tape 
mark  written  when  the  file  is  subsequently  closed. 
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Example: 


OPEN  1 


OPEN  1,1 
OPEN  1,1,0 
OPEN  1,1,0, "DAT 


Open  logical file  1  at  cassette  drive  #7  (default) for  a 
read  access  (default)  from  the  first  file 
encountered  on  the  tape  (no  file  name 
specified) 

Same  as  above 

Same  as  above 


ii 


Same  as  above  but  access  the  file  named  DAT 


OPEN  3,1,2 


Open  logical  file  3  for  cassette  #7  for  a  write  with 
EOT  (End  of  Tape)  access.  The  new  file  is 
unnamed  and  will  be  written  at  the  current 
physical  tape  location 


OPEN  3,1,2, "PENTAGRAM 


Same  as  above  but  access  the  file  named 


PENTAGRAM 


Disk  Data  File  Format 

OPEN  lf,dev,sa, "dr filename, type[,accessY 

The  file  named  filename  on  the  diskette  in  drive  dr  is  opened  and 
assigned  logical  file  number  If.  The  type  identifies  the  file  as  sequential  (SEQ), 
program  (PRG),  or  random  (USR).  If  the  file  is  sequential,  access  must  be 
WRITE  to  specify  a  write  access  or  READ  to  specify  a  read  access.  Access  is 
not  present  for  a  program  or  random  access  file. 

An  existing  sequential  file  can  be  opened  for  a  write  access  if  dr  is 
preceded  by  an  @  sign.  The  existing  sequential  file  contents  are  replaced 
entirely  by  new  written  data. 

The  device  number  dev  must  be  present;  it  is  8  for  all  standard  disk  units. 
If  dev  is  absent,  a  default  value  of  1  is  assumed  and  the  primary  tape  cassette 
unit  is  selected. 

For  a  data  file  the  secondary  address  sa  can  have  any  value  between  2  and 
14,  but  every  open  data  file  should  have  its  own  unique  secondary  address.  A 
secondary  address  of  15  selects  the  disk  unit  command  channel.  Secondary 
addresses  of  0  and  1  are  used  to  access  program  files.  Secondary  address  0  is 
used  to  load  a  program  file;  secondary  address  1  is  used  to  save  a  program  file. 

Example: 

OPEN  1 ,  8,  2,  "0  :  DAT,  SEQ,  READ"  Open  logical  file  1  on  a  diskette  in  drive  0.  Read 

from  sequential  file  DAT 

OPEN  5 ,  8 , 3 ,  "  1 :  NEWF I LE ,  SEQ ,  WRITE  "    Open  logical  file  5  on  a  diskette  in  drive  1.  Write  to 

sequential  file  NEW  FILE 
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OPEN  4,8,4,  "Ql  ,NEUFILE,SEQi  WRITE"   Open  logical  file  4  on  diskette  drive  1.  Write  to 

sequential  file  NEWFILE  replacing  prior 
contents 

PAINT 

Paints  a  selected  area  the  specified  color. 

Format: 

PAINT  C,  X,  Y,  M 

where  C  is  the  color,  X  and  Y  specify  any  point  inside  the  area  to  be  painted, 
and  M  selects  the  area  mode. 

PLAY 

Plays  a  note  or  series  of  notes. 

Format: 

play  vn,  on,  En,  un,  xn,  m 

where  V#  is  the  voice  number,  Ott  is  the  octave,  Ett  is  the  envelope  number,  U# 
is  the  volume,  and  M  is  the  music.  For  more  details,  see  Chapter  7. 

POKE 

The  POKE  statement  stores  a  byte  of  data  in  a  specified  memory 
location. 

Format: 

POKE  memadr,byte 

A  value  between  0  and  255,  provided  by  byte,  is  loaded  into  the  memory 
location  with  the  address  memadr. 

Example: 

10  POKE  1 ,  fl  POKE  value  of  variable  A  into  memory  at  address 

1 

POKE  32768,  flSC<  "fl"  )-64  POKE  1  (the  value  of  ASCC'A")-64)  into  memory 

at  address  32768 

PRINT 

The  PRINT  statement  displays  data;  it  is  also  used  to  print  to  the  line 
printer. 
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Format: 


(PRINT*  f,\  f,\ 

<      ?       >  data    <   >  data...   <;>  data 


PRINT  Field  Formats 

Numeric  fields  are  displayed  using  standard  numeric  representation  for 
numbers  greater  than  0.01  and  less  than  or  equal  to  999999999.  Scientific 
notation  is  used  for  numbers  outside  of  this  range.  Numbers  are  preceded  by  a 
sign  character  and  are  followed  by  a  blank  character. 

sign  blank 
|    number  J 

SNNN,  ...NN  b 

Numeric  field  display 

The  sign  is  a  blank  for  a  positive  number  and  a  minus  sign  (— )  for  a  negative 
number. 

Strings  are  displayed  without  additions  or  modifications. 
PRINT  Formats 

First  data  item.  The  first  data  item  is  displayed  at  the  current  cursor 
position.  The  PRINT  format  character  (comma  or  semicolon)  following  the 
first  data  item  specifies  the  location  of  the  second  data  item's  display.  The 
location  of  each  subsequent  data  item's  display  is  determined  by  the  punctua- 
tion following  the  preceding  data  item.  Data  items  may  be  in  the  same  PRINT 
statement  or  in  a  separate  PRINT  statement. 

New  line.  When  no  comma  or  semicolon  follows  the  last  data  item  in  a 
PRINT  statement,  a  carriage  return  occurs  after  the  last  data  item  is 
displayed. 

Tabbing.  A  comma  following  a  data  item  causes  the  next  data  item  to  be 
displayed  at  the  next  default  tab  column.  Default  tabs  are  at  columns  1,  11, 
and  21 .  If  a  comma  precedes  the  first  data  item,  a  tab  will  precede  the  first  item 
display. 

Continuous.  A  semicolon  following  a  data  item  causes  the  next  display 
to  begin  immediately  in  the  next  available  column  position.  Numeric  data 
always  has  one  trailing  blank  character.  For  string  data,  items  are  displayed 
continuously  with  no  forced  intervening  spaces. 
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Example: 

49  PRINT  fl 

40  PRINT  fl,B,C 

40  PRINT  fl;B;C 

49  PRINT,  R;B;C 

40  PRINT  "NUMBERS", fi;B;C 

40  PRINT  "NUM'VBER"; 

41  PRINT  ms%a;b;c 

PRINT* 

The  Print  External  statement  (PRINT#)  outputs  one  or  more  data  items 
from  the  computer  to  an  external  device  (cassette  tape  unit,  disk  unit,  or 
printer)  identified  by  a  logical  file  number. 

Format: 

PRmjniffdata;CHR$(13);data;CHR$(13)f . . .  ,CHR$(13);data 

Data  items  listed  in  the  PRINT#  statement  parameter  list  are  written  to 
the  external  device  identified  by  logical  unit  number  If. 

Very  specific  punctuation  rules  must  be  observed  when  writing  data  to 
external  devices.  A  brief  summary  of  punctuation  rules  is  given  below. 

PRINT#  Output  to  Cassette  Files 

Every  numeric  or  string  variable  written  to  a  cassette  file  must  be  followed  by 
a  carriage  return  character.  This  carriage  return  character  is  automatically 
output  by  a  PRINT#  statement  that  has  a  single  data  item  in  its  parameter  list. 
But  a  PRINT#  statement  with  more  than  one  data  item  in  its  parameter  list 
must  include  characters  that  force  carriage  returns.  For  example,  use 
CHR$(  13)  to  force  a  carriage  return,  or  a  string  variable  that  has  been  equated 
to  CHR$(13)  such  as  c5=CHR$(13). 

PRINT#  Output  to  Diskette  Files 

The  cassette  output  rules  described  above  apply  also  to  diskette  files,  with  one 
exception:  Groups  of  string  variables  can  be  separated  by  comma  characters 
(CHR$(44)).  The  comma  character  separators,  like  the  carriage  return  separat- 
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ors,  must  be  inserted  using  CHR$.  String  variables  written  to  diskette  files 
with  comma  character  separators  must  subsequenty  be  read  back  by  a  single 
INPUT#  statement.  The  INPUT#  statement  reads  all  text  from  one  carriage 
return  character  to  the  next. 

PRINT#  Output  to  the  Line  Printer 

When  the  Print#  statement  outputs  data  to  a  line  printer,  CHR$  must  equal 
CHR$(29).  No  punctuation  characters  should  separate  CHR$  from  data 
items,  as  illustrated  in  the  PRINT#  format  definition. 

Caution:  The  form  ?#  cannot  be  used  as  an  abbreviation  for  PRINT#. 

READ 

The  READ  statement  assigns  values  from  a  DATA  statement  to  vari- 
ables named  in  the  READ  parameter  list. 

Format: 

READ  var[,var, . . .  ,var] 

READ  is  used  to  assign  values  to  variables.  READ  can  take  the  place  of 
multiple  assignment  statements  (see  LET=). 

READ  statements  with  variables  lists  require  corresponding  DATA 
statements  with  lists  of  constant  values.  The  data  constants  and  correspond- 
ing variables  have  to  agree  in  type.  A  string  variable  can  accept  any  type  of 
constant;  a  numeric  variable  can  accept  only  numeric  constants. 

The  number  of  READ  and  DATA  statements  can  differ,  but  there  must 
be  an  available  DATA  constant  for  every  READ  statement  variable.  There 
can  be  more  data  items  than  READ  statement  variables,  but  if  there  are  too 
few  data  items  the  program  aborts  with  an  ?OUT  OF  DATA  error  message. 

READ  is  generally  executed  in  program  mode.  It  can  be  executed  in 
immediate  mode  as  long  as  there  are  corresponding  DATA  constants  in  the 
current  stored  program  to  read  from. 

Example: 

10  DflTR  1.2.3  On  completion,  A=l,  B=2,  C=3 

20  RERD  R,B,C 

150  RERD  C$,dfFt      On  completion,  C$="STR",  D=14.5,  F$="TM" 

160  DRTfl  STR 

170  DRTR  14.5, "TM" 


BASIC  STATEMENTS  497 


REM 

The  Remark  statement  (REM)  allows  comments  to  be  placed  in  the 
program  for  program  documentation  purposes. 

Format: 

REM  comment 

where  comment  is  any  sequence  of  characters  that  will  fit  on  the  current 
80-column  line. 

REM  statements  are  reproduced  in  program  listings,  but  they  are  other- 
wise ignored.  A  REM  statement  may  be  placed  on  a  line  of  its  own,  or  it  may 
be  placed  as  the  last  statement  on  a  multiple-statement  line. 

A  REM  statement  cannot  be  placed  ahead  of  any  other  statements  on  a 
multiple-statement  line,  since  all  text  following  the  REM  is  treated  as  a 
comment.  REM  statements  may  be  placed  in  the  path  of  program  execution, 
and  they  may  be  branched  to. 

Example: 

10  REM  *******  *** 

20  REM  *#*PR0GRflM  EXCflLIBUR*** 

30  GOTO  55  REM  BRRNCH  IF  OUT  OF  DATA 

RENUMBER 

Renumbers  a  BASIC  program  according  to  the  following  parameters: 
RENUMBER  N,  I,  O 

where  N  is  the  new  starting  line  number,  I  is  the  increment  between  the  lines, 
and  O  is  the  old  starting  line  number. 

RESTORE 

The  RESTORE  statement  resets  the  DATA  statement  pointer  to  the 
beginning  of  data. 

Format: 

RESTORE 

RESTORE  may  be  given  in  immediate  or  program  mode. 
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Example: 

10  DATA  1,2, N44 

20  READ  A,B,B$  A=l,  B=2,  B$="N44" 
30  RESTORE 

40  READ  X,V,Z*  x=]>  Y=2>  z$="N44" 


RETURN 

The  RETURN  statement  branches  program  control  to  the  statement  in 
the  program  following  the  most  recent  GOSUB  call.  Each  subroutine  must 
terminate  with  a  RETURN  statement. 

Format: 

RETURN 

Example: 

100  RETURN 

Note  that  the  RETURN  statement  returns  program  control  from  a 
subroutine,  whereas  the  RETURN  key  moves  the  cursor  to  the  beginning  of  the 
next  display  line.  The  two  are  not  related  in  any  way. 

RUN 

RUN  begins  execution  of  the  program  currently  stored  in  memory.  RUN 
closes  any  open  files  and  initializes  all  variables  to  0  or  null  values. 

Format: 

RUN[line] 

When  RUN  is  executed  in  immediate  mode,  the  computer  performs  a 
CLR  of  all  program  variables  and  resets  the  data  pointer  in  memory  to  the 
beginning  of  data  (see  RESTORE)  before  executing  the  program. 

If  RUN  specifies  a  line  number,  the  computer  still  performs  the  CLR  and 
RESTORES  the  data,  but  execution  begins  at  the  specified  line  number.  RUN 
specifying  a  line  number  should  not  be  used  following  a  program  break  —  use 
CONT  or  GOTO  for  that  purpose. 

RUN  may  also  be  used  in  program  mode.  It  restarts  program  execution 
from  the  beginning  of  the  program  with  all  variables  cleared  and  data 
pointers  reinitialized. 
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Example: 

RUN  Initialize  and  begin  execution  of  the  current  program 

RUN  1 000  Initialize  and  begin  execution  of  the  program  start- 

ing at  line  1000 

SAVE 

The  SAVE  statement  writes  a  copy  of  the  current  program  from  memory 
to  an  external  device. 

Cassette  Unit  Format 

SAVE["filename"]ldev]lsa] 

The  SAVE  statement  writes  the  program  that  is  currently  in  memory  to 
the  tape  cassette  drive  specified  by  dev.  If  the  dev  parameter  is  not  present,  the 
assumed  value  is  1  and  the  primary  cassette  drive  is  selected.  The  filename,  if 
specified,  is  written  at  the  beginning  of  the  program.  If  a  nonzero  secondary 
address  (sa)  is  specified,  an  end-of-file  mark  is  written  on  the  cassette  after  the 
saved  program. 

Although  no  SAVE  statement  parameters  are  required  when  writing  to  a 
cassette  drive,  it  is  a  good  idea  to  name  all  programs.  A  named  program  can 
be  read  off  cassette  tape  either  by  its  name  or  by  its  location  on  the  cassette 
tape.  A  program  with  no  name  can  be  read  off  cassette  tape  by  its  location 
only. 

The  SAVE  statement  is  most  frequently  used  in  immediate  mode, 
although  it  can  be  executed  from  within  a  program. 

Example: 

SAVE  Write  the  current  program  onto  the  cassette  in  drive 

1,  leaving  it  unnamed 

SAVE  "  RED  "  Write  the  current  program  onto  the  cassette  in  drive 

1,  assigning  the  file  name  of  RED 

fliM  "  RED  "  Same  as  above 

SAVE  A* 

SAVE  "  BLACKJACK  %  2  >  1       Write  the  current  program  onto  the  cassette  in  drive 

2,  naming  the  program  BLACKJACK.  Write 
an  end-of-file  mark  after  the  program 

Diskette  Drive  Format 

SAVE  "dr filename", dev 
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The  SAVE  statement  writes  a  copy  of  the  current  program  from  memory 
to  the  diskette  in  the  drive  specified  by  dr.  The  program  is  given  the  name  file- 
name. The  dev  must  be  present;  normally,  it  has  the  value  8.  If  dev  is  absent,  a 
default  value  of  1  is  assumed  and  the  cassette  is  selected. 

The  file  name  assigned  to  the  program  must  be  new.  If  a  file  with  the 
same  name  already  exists  on  the  diskette,  a  syntax  error  is  reported.  However, 
a  program  file  can  be  replaced;  if  an  @  sign  precedes  dr  in  the  SAVE  statement 
text  string,  the  program  replaces  the  contents  of  a  current  file  named  file- 
name. 

The  diskette  SAVE  statement  is  also  used  primarily  in  immediate  mode 
although  it  can  be  executed  out  of  a  program. 

SCALE 

Changes  the  graphics  screen  coordinate  from  320  X  200  to  32767  X 
32767. 

Format: 

SCALE  N 

where  N  is  either  Scaling  ON  (1)  or  OFF  (0). 
SCNCLR 

Clears  the  graphics  screen  or  (with  parameters)  other  screens.  The 
options  are 

0=40-column  text 

1  =  bit-mapped 

2= split  screen 

3= multi-color  bit-mapped 

4=  split  screen  multi-color 

5=80-column  text 

SCRATCH 

The  SCRATCH  statement  erases  a  single  file  from  a  diskette. 

Format: 

SCRATCH  [Ddyfllenamen[OS  Uz] 

The  file  named  filename  on  the  diskette  in  drive  d  is  deleted.  If  the  d 
parameter  is  not  present,  drive  0  is  assumed. 

The  SCRATCH  statement  is  used  in  immediate  mode  and  in  program 
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mode.  In  immediate  mode  the  statement  is  used  to  perform  general  diskette 
housekeeping  operations.  When  executed,  the  message  ARE  YOU  SURE?  is 
displayed.  You  must  key  the  response  YES  <CR>  or  Y  <CR>,  or  the  file 
will  not  be  scratched. 

When  the  SCRATCH  statement  is  executed  out  of  a  program,  no 
prompt  messages  are  displayed.  Temporary  data  files  are  frequently  created 
by  a  program  to  hold  transient  data  that  will  not  fit  in  available  memory. 
Temporary  data  files  should  be  scratched  before  the  program  completes 
execution;  otherwise  a  FILE  EXISTS  syntax  error  will  be  generated  when  the 
program  is  run  next. 

Files  must  be  closed  before  they  are  scratched.  If  you  attempt  to  scratch 
an  open  file  the  C-128  computer  may  perform  complex,  erroneous  diskette 
operations. 

If  using  DOS  2.0  it  is  a  good  idea  to  COLLECT  the  diskette  in  imme- 
diate mode  before  scratching  any  files. 

Example: 

SCRATCH  DO,  "DUMMV1 "  Scratch  file  DUMMYl  on  diskette  drive  0 

SCRATCH  "DUMMVl"  Same  as  above 

SCRATCH  Dl ..  "FILE1  "  Scratch  FILE1  on  diskette  drive  I 

SLEEP 

Delay  a  program  for  a  specified  length  of  time. 

Format: 

SLEEP  S 

S  is  the  number  of  seconds  to  delay  (0-65535). 
SLOW 

Opposite  of  FAST.  Switches  the  C-128  to  1  Mhz  mode. 

Format: 
SLOW 

SOUND 

Creates  a  sound  with  the  SID  chip. 
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Format: 

SOUND  V,  F,  D,  S,  MF,  W,  P 

where  Fis  the  voice,  Fis  the  frequency,  D  is  the  duration  of  the  sound  in  60ths 
of  a  second,  MFis  the  minimum  frequency  for  a  sweep,  S  is  the  step  value  for 
a  sweep  (0= no  sweep),  fFis  the  wave  form,  and  P  is  the  pulse  width.  For  more 
information  on  SOUND,  see  Chapter  7. 

SPRCOLOR 

Defines  the  two  multi-color  sprite  colors. 

Format: 

SPRCOLOR  N,  C 

where  N  is  the  multi-color  number  and  C  is  the  color  you  want. 
SPRDEF 

Starts  the  sprite  editor.  For  more  information  on  SPRDEF,  see  Chapter  6. 

SPRITE 

Sets  sprite  parameters. 

Format: 

SPRITE  N,  O,  F,  P,  X,  Y,  M 

where  N  is  the  sprite  number,  O  turns  the  sprite  ON  (1)  or  OFF  (0),  F  is  the 
foreground  color,  Pis  the  sprite  priority,  Zand  Y are  the  expand  functions, 
and  M  is  multi-color  (ON/ OFF). 

TEMPO 

This  changes  the  speed  of  a  PLAY  command. 

Format: 

TEMPO  S 

where  S  is  a  value  between  0  and  255.  Default  value  is  8. 
STOP 


The  STOP  statement  causes  the  program  to  stop  execution  and  return 
control  to  C-128  BASIC.  A  break  message  is  displayed  on  the  screen. 
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Format: 
STOP 

Example: 

655  STOP       Will  cause  the  message  BREAK  IN  655  to  be 
displayed 

VALIDATE 

Format: 

PRINT#///'V[ALIDATE][</r]" 

The  diskette  in  drive  dr  is  validated.  If  the  dr  parameter  is  absent,  the 
diskette  in  the  most  recently  selected  drive  is  validated. 

When  a  diskette  is  validated,  a  new  Block  Availability  Map  is  created  for 
all  valid  data  files  on  the  diskette.  Any  files  that  were  improperly  closed  or 
were  not  closed  become  invalid  files;  they  are  deleted  from  the  diskette  and 
their  diskette  space  is  released. 

Do  not  validate  a  diskette  that  contains  random  access  files;  validation 
will  erase  the  random  access  file.  If  a  read  error  occurs  during  validation,  the 
validation  operation  is  aborted  and  the  diskette  is  left  in  its  initial  state.  A 
diskette  must  be  initialized  after  it  is  validated. 

Example: 

OPEN  1 >  8> 15  Open  the  diskette  command  channel 

PR  I  NT#  1  /'  1 0  "  Initialize  the  diskette  in  drive  0 

PR  I  HT#  1  ,n  VO  "  Validate  the  diskette  in  drive  0 

VERIFY 

The  VERIFY  statement  compares  the  current  program  in  memory  with 
the  contents  of  a  program  file. 

Cassette  Unit  Format 

VERlFY["filename"]ldev] 

The  program  currently  in  memory  is  compared  with  the  program  named 
filename  on  the  cassette  in  the  unit  specified  by  dev. 
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If  dev  is  not  present,  a  default  of  1  is  assumed  and  cassette  unit  1  is 
selected.  If filename  is  not  present,  the  next  file  on  the  cassette  in  the  selected 
unit  is  verified. 

You  should  always  verify  a  program  immediately  after  saving  it.  The 
VERIFY  statement  is  almost  always  executed  in  immediate  mode. 

Example: 

VERIFV  Verify  the  next  program  found  on  the  tape 

VERIFV  "CLIP"  Search  for  the  program  named  CLIP  on  cassette 

unit  #/  and  verify  it 

fl$ *  "  CL I P  "  Same  as  above 

VERIFV  fl$ 

Diskette  Drive  Format 

VERIFY  "dr;filename'\dev 

The  program  currently  stored  in  memory  is  compared  with  the  program 
file  named  filename  on  the  diskette  in  drive  dr.  The  dev  parameter  must  be 
present  and  unless  otherwise  specified  it  must  have  the  value  8.  If  the  dev 
parameter  is  absent,  a  default  value  of  1  is  assumed  and  the  primary  cassette 
drive  is  selected. 

In  order  to  verify  the  program  most  recently  saved,  use  the  following 
version  of  the  VERIFY  statement: 

VERIFV  "*",8 

You  should  always  verify  programs  as  soon  as  you  have  saved  them.  The 
VERIFY  statement  is  nearly  always  executed  in  immediate  mode. 

Example: 

VER I F  V  "  %  " » 8  Verify  the  program  just  saved 

VERIFV"0:  SHELL'S  8  Search  for  the  program  named  SHELL  on  disk 

drive  0  and  verify  it 
C$«  "  0 :  SHELL  "  Same  as  above 

VERIFV  C$ 


VOL 

Controls  the  loudness  of  a  SOUND  command. 
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Format: 
VOLN 

where  TV  is  a  value  from  0  (quiet)  to  15  (loud). 
WAIT 

The  WAIT  statement  halts  program  execution  until  a  specified  memory 
location  acquires  a  specified  value. 

Format: 

WAIT  memadr,mask[,xor] 

where  mask  is  a  one-byte  mask  value  and  xor  is  a  one-byte  mask  value. 
The  WAIT  statement  executes  as  follows: 

1.  The  contents  of  the  addressed  memory  location  are  fetched. 

2.  The  value  obtained  in  step  1  is  Exclusive-ORed  with  xor,  if  present.  If 
xor  is  not  specified,  it  defaults  to  0.  When  xor  is  0,  this  step  has  no 
effect. 

3.  The  value  obtained  in  step  2  is  ANDed  with  the  specified  mask  value. 

4.  If  the  result  is  0,  WAIT  returns  to  step  1 ,  remaining  in  a  loop  that  halts 
program  execution  at  the  WAIT. 

5.  If  the  result  is  not  0,  program  execution  continues  with  the  statement 
following  the  WAIT  statement. 

The  STOP  key  will  not  interrupt  WAIT  statement  execution. 
WIDTH 

Changes  the  width  of  the  lines  drawn  in  DRAW.  The  options  are  1  (single 
width)  and  2  (double  width). 

WINDOW 

Establishes  a  functional  window  inside  the  normal  screen  window. 
Format: 

WINDOW  TLC,  TLR,  BRC,  BRR,  C 

where  TLC  is  the  top-left  column,  TLR  is  the  top-left  row,  BRC  is  the 
bottom-right  column,  and  BRR  is  the  bottom-right  row.  C  determines 
whether  the  new  window  will  be  cleared  when  it  is  defined. 


 APPENDIX 

BASIC  Functions 


The  C-128  can  define  a  great  number  of  functional  operations  directly  from 
BASIC.  These  functions  include  mathematical  derivations,  screen  formatting 
instructions,  and  string  manipulators.  They  are  listed  in  alphabetical  order. 

ABS 

ABS  returns  the  absolute  value  of  a  number. 

Format: 

ABS(data  ri) 

Example: 

fl*ABS<10>  Results  in  A=  10 

fl«ABS<-10)  Results  in  A=  10 

PRINT  flBS<X),flBS<V),flBS<Z> 

ASC 

ASC  returns  the  ASCII  code  number  for  a  specified  character. 
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Format: 

ASC(data$) 

If  the  string  is  longer  than  one  character,  ASC  returns  the  ASCII  code 
for  the  first  character  in  the  string.  The  returned  argument  is  a  number  and 
may  be  used  in  arithmetic  operations. 

Example: 

?flSC<"RH>  Prints  65 

X-flSCC'S") 

?X  Prints  the  ASCII  value  of  "S,"  which  is  83 

ATN 

ATN  returns  the  arctangent  of  the  argument. 

Format: 

XTN(data  n) 

ATN  returns  the  value  in  radians  in  the  range  ±  17. 

Example: 

fl»flTN<flG> 
?180ir*flTN<fl) 

BUMP 

Stores  a  numeric  value  that  corresponds  to  the  objects  (if  any)  that  have 
collided  on  the  video  display.  BUMP  has  a  single  parameter,  which  can  be 
either  1  or  2. 

BUMP(l)  examines  sprite-to-sprite  collisions.  The  sprites  are  each 
assigned  a  bit  in  the  BUMP  register.  Sprite  0  is  bit  0,  sprite  1  is  bit  1 ,  and  so  on. 
To  determine  which  sprites  have  collided,  AND  the  value  in  the  BUMP 
register  with  the  binary  value  of  the  bit  position  of  the  sprite.  To  determine 
whether  sprite  2  was  in  a  collision,  AND  the  value  in  the  BUMP  register  with 
2A2  (4).  For  example,  BUMP(2)  examines  sprite-to-screen  character  collisions. 
The  register  works  the  same  as  shown  earlier. 

Example: 

IF  BUMP(l)  AND  4=4  THEN  PRINT  "BUMP  SPRITE  #2!" 
IF  BUMP (2)    AND  4=4  THEN  PRINT   "BUMP  SPRITE  #2!" 
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CHR$ 

CHRS  returns  the  string  representation  of  the  specified  ASCII  code. 

Format: 

CHR$(ty/e) 

CHRS  can  be  used  to  specify  characters  that  cannot  be  represented  in 
strings.  These  include  a  carriage  return  and  the  double  quotation  mark. 

Example: 

IF  C$»CHR$<  13)  GOTO  10  Branch  if  C$  is  a  carriage  return  (CHR$(13)) 

?CHR$ <34) :  "HOHOHO" :  CHR$<34)  Print  the  eight  characters  "HOHOHO"  (where 

CHR$(34)  represents  a  double  quotation  mark) 

COS 

COS  returns  the  cosine  of  the  argument. 

Format: 

QOS{data  n) 

DEC 

Converts  a  hexadecimal  number  into  a  decimal  number. 
Example: 

A=DEC<HFFFF") 
PRINT  A 
65535 

ERR$ 

This  is  a  system  string  that  contains  the  text  that  describes  the  last  error 
that  the  C-128  encountered. 

Example: 

PRINT  ERR* 
STRING  TOO  LONG 
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EXP 

EXP  returns  the  value  earg.  The  value  of  e  used  is  2.71828183. 

Format: 

EXP(tfrg  n) 

The  arg  n  must  have  a  value  in  the  range  ±88.029691 .  A  number  larger 
than  +88.029691  will  result  in  an  overflow  error  message.  A  number  smaller 
than  -88.029691  will  yield  a  zero  result. 


Example: 
?EXP<0) 
?EXP<1) 
EV»EXP<2> 
EB«EXP<50.24) 
?EXP<66. 0296919) 
?EXP (-88.0296919) 
?EXP (88.029692) 
?EXP( -88. 029692) 


Prints  1 

Prints  2.71828183 

Results  in  EV=7.3890561 

Results  in  EB=6.59105247E+21 

Largest  allowable  number,  yields  1 .70141 183E+38 

Smallest  allowable  number,  yields  5.87747176E-39 

Out  of  range,  overflow  error  message 

Out  of  range,  returns  0 


FNxx 

A  system  variable  that  contains  the  last  computed  value  of  the  most 
recently  used,  user  defined  function. 

Example: 

10  DEF  FNJJ(A)=PI*A 

20   INPUT  A 

30  PRINT  FNJJ(A) 


FRE 

FRE  is  a  system  function  that  collects  all  unused  bytes  of  memory  into 
one  block  (called  "garbage  collection")  and  returns  the  number  of  free  bytes. 

Format 

FRE(arg) 

The  arg  is  a  dummy  argument.  It  may  be  string  or  numeric. 
FRE  can  be  used  anywhere  a  function  may  appear,  but  it  is  normally 
used  in  an  immediate  mode  PRINT  statement. 
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Example: 

?FRE( 1 )  Institute  garbage  collection  and  print  the 

number  of  free  bytes 

HEX$ 

Converts  a  decimal  number  into  a  hexadecimal  number. 
Example: 

A=HEX$ (65535) 
PRINT  A 
FFFF 


INSTR 

String  search  function.  Locates  a  small  string  within  a  larger  one  and 
returns  the  smaller  string's  position  (in  characters)  within  the  larger  one. 

Example: 

A$= INSTR    ("THE  QUICK  BROWN  FOX " , "OWN" ) 

PRINT  A* 

13 


INT 

INT  returns  the  integer  portion  of  a  number,  rounding  to  the  next  lower 
signed  number. 

Format: 

mT{arg  n) 

For  positive  numbers,  INT  is  equivalent  to  dropping  the  fractional 
portion  of  the  number  without  rounding.  For  negative  numbers,  INT  is 
equivalent  to  dropping  the  fractional  portion  of  the  number  and  adding  1 . 
Note  that  INT  does  not  convert  a  floating  point  number  (5  bytes)  to  integer 
type  (2  bytes). 

Example: 

fl*INT<1.5>      Results  in  A=l 
fl»INT<-1.5)     Results  in  A=-2 


X*  I  NT  <  -0 . 1 )     Results  in  X=- 1 
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A  caution  here:  since  floating  point  numbers  are  only  close  approxima- 
tions of  real  numbers,  an  argument  may  not  yield  the  exact  INT  function 
value  you  might  expect.  For  instance,  consider  the  number  3.89999999.  The 
function  INT(3. 89999999)  would  yield  a  3  answer,  not  4  as  would  be  expected. 

?INT<3. 89999999) 

3 

JOY 

A  system  variable  that  contains  a  numeric  value  that  corresponds  to  the 
current  position  of  a  specified  joystick.  The  numeric  positions  are: 

1=UP 

8= LEFT/  UP  2=  UP/  RIGHT 

7= LEFT  3=  RIGHT 

6= LEFT/  DOWN  4=  DOWN/  RIGHT 

5=  DOWN 
0=NO  MOVEMENT 

If  the  number  returned  JOY  is  greater  than  128  then  the  FIRE  button  is 
pressed. 

Example: 

PRINT  JOY(l) 
7 

indicates  that  JOYSTICK  1  is  sending  LEFT  signals. 

PRINT  JOY(l) 
135 

indicates  that  JOYSTICK  1  is  sending  LEFT  signals  and  the  FIRE  button  is 
pressed  (135- 128=7). 

LEFT$ 

LEFTS  returns  the  leftmost  characters  of  a  string. 

Format: 

LEFT$(arg$,byte) 
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The  byte  specifies  the  number  of  leftmost  characters  to  be  extracted  from 
the  arg$  character  string. 

Example: 

?LEFT*<,,flRG%2)         Prints  AR 

fl$-LEFT$(B$,  10)         Prints  leftmost  ten  characters  of  the  string  B$ 

LEN 

LEN  returns  the  length  of  the  string  argument. 

Format: 

LEN(arg$) 

LEN  returns  a  number  that  is  the  count  of  characters  in  the  specified 
string. 

Example: 

?LEN("flBCDEF")  Displays  6 

N*LEN<C$+B*>  Displays  the  sum  of  characters  in  strings  C$  and  D$ 

LOG 

LOG  returns  the  natural  logarithm,  or  log,  to  the  base  e.  The  value  of  e 
used  is  2.71828183. 

Format: 

LOG(arg  n) 

An  ILLEGAL  QUANTITY  ERROR  message  is  returned  if  the  argu- 
ment is  zero  or  negative. 

Example: 

?L0G<1)  Prints  0 

fl*LOG<10)  Results  in  A=2.30258509 

R*L0G<1E6)  Results  in  A=  13.8155106 

A«L0G<X  VL0G<  10)  Calculates  log  to  the  base  10 
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MID$ 

MID$  returns  any  specified  portion  of  a  string. 
Format: 

MJD$(data$,bytei[,byte2]) 

Some  number  of  characters  from  the  middle  of  the  string  identified  by 
data$  is  returned.  The  two  numeric  parameters  bytei  and  bytei  determine  the 
portion  of  the  string  which  is  returned.  String  characters  are  numbered  from 
the  left,  with  the  leftmost  character  having  position  1.  The  value  of  bytei 
determines  the  first  character  to  be  extracted  from  the  string.  Beginning  with 
this  character,  bytei  determines  the  number  of  characters  to  be  extracted.  If 
bytei  is  absent  then  all  characters  up  to  the  end  of  the  string  are  extracted. 

An  ILLEGAL  QUANTITY  ERROR  message  is  printed  if  a  parameter  is 
out  of  range. 

Example: 

?MID$<"RBCDE%2,1>  Prints  B 

?MID$<'"ABCDE%3,2>  Prints  CD 

?MID*<MRBCDE%3>  Prints  CDE 

PEEK 

PEEK  returns  the  contents  of  the  specified  memory  location.  PEEK  is 
the  counterpart  of  the  POKE  statement. 

Format: 

PEEK(wem  adr) 

Example: 

?PEEK<1 )  Prints  contents  of  memory  location  1 

fi»PEEK<20000) 

PEN 

Five  system  variables  that  contain  information  on  the  position  of  the 
light  pen,  which  are  shown  here. 
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l  =  X  position  of  light  pen  (40-col) 
2=  Y  position  of  light  pen  (40-col) 
3=X  position  of  light  pen  (80-col) 
4—  Y  position  of  light  pen  (80-col) 
5=  Light  pen  trigger  value 

Example: 

PRINT  PEN(l) ,   PEN (2) 
100, 100 

Indicates  that  the  light  pen  is  at  dot  position  100,100. 
POINTER 

A  system  variable  that  contains  the  actual  memory  address  of  a  specified 
variable. 

PRINT  POINTER (A*) 
12349 

POS 

POS  returns  the  column  position  of  the  cursor. 

Format: 

POS(data) 

The  data  is  a  dummy  function;  it  is  not  used  and  therefore  can  have  any 
value.  POS  returns  the  current  cursor  position.  If  no  cursor  is  displayed,  the 
current  character  position  within  a  program  line  or  string  variable  is 
returned.  Character  positions  begin  at  0  for  the  leftmost  character. 

Recall  that  program  logic  processes  80 -character  lines  even  though  the 
C-128  computer  has  a  40 -character  display.  If  program  logic  in  such  a 
computer  is  processing  a  character  in  the  second  half  of  the  line,  the  POS 
function  will  return  a  value  between  the  beginning  and  end  of  the  line  (in 
other  words,  41  to  80). 

By  concatenation,  string  variables  with  up  to  255  characters  may  be 
generated.  If  program  logic  is  processing  a  long  string,  then  the  POS  func- 
tion will  return  the  character  position  currently  being  processed.  Under 
these  circumstances  the  POS  function  will  return  a  value  in  the  range 
between  0  and  255. 
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Example: 

?POS<  1 )  At  the  beginning  of  a  line,  returns  0 

?"RBCRBC" ;  P0S(  1 )        With  a  previous  POS  value  of  0,  displays  a  POS  value  of  6 


POT 

System  variables  that  contain  the  current  value(s)  of  the  paddle  con- 
trollers (1-4).  The  POT  parameters  are 

POT(l)  =  Current  position  of  paddle  1 
POT(2)  =  Current  position  of  paddle  2 
POT(3)  =  Current  position  of  paddle  3 
POT(4)  =  Current  position  of  paddle  4 

The  POT  values  range  from  0-255.  If  the  value  in  POT(A0  is  greater  than 
255,  then  the  FIRE  button  is  pressed. 

Example: 

PRINT  POT(l) 
7 

indicates  that  PADDLE  1  is  in  location  1. 

PRINT  POT(l) 
355 

indicates  that  PADDLE  1  is  in  screen  position  100  and  the  FIRE  button  is 
pressed  (355-255=100). 

RCLR 

System  variables  that  contain  the  color(s)  of  the  following: 

0=  background  (40-column) 

I  =  foreground  (bit  map) 

2—  multi-color  #1 

3=  multi-color  #2 

4=  border  (40-column) 

5=  character  color 

6— background  (80-column) 

Example: 


PRINT  RCLR(O) 
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This  indicates  that  the  40-column  background  is  at  the  default  value  (12). 
RDOT 

System  variable  that  contains  the  current  position  of  the  pixel  cursor. 
The  parameters  are 

0=  X  coordinate  of  pixel  cursor 
1  =  Y  coordinate  of  pixel  cursor 
2=  Color  of  pixel  cursor 

RGR 

System  variable  containing  the  numeric  value  of  the  current  graphics 
mode.  The  options  are: 

0=  40-column  text 

1  =  40-column  bit  map 

2=  split  screen 

3=  multi-color  bit  map 

4=  split  screen  multi-color 

5=  80-column  text 

RIGHT$ 

RIGHTS  returns  the  rightmost  characters  in  a  string. 

Format: 

R\GWY$(arg$,byte) 

The  byte  identifies  the  number  of  rightmost  characters  that  are  extracted 
from  the  string  specified  by  arg$. 

Example: 

R I  GHT$  <  flRG ,  2 )  Displays  RG 

MM$*RIGHT$(X$+H#%5)       MM$  is  assigned  the  last  four  characters  of  X$, 

plus  the  character  # 

RND 

RND  generates  random  number  sequences  ranging  between  0  and  1 . 
Format: 


RND(arg  ri)  Return  random  number 

RND  (— arg  ri)       Store  new  seed  number 
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Example: 

fi*RND<-l )  Store  a  new  seed  based  on  the  value  —  1 

fl3RND<  1 )  Fetch  the  next  random  number  in  sequence 

An  argument  of  zero  is  treated  as  a  special  case;  it  does  not  store  a  new 
seed,  nor  does  it  return  a  random  number.  RND(O)  uses  the  current  system 
time  value  TI  to  introduce  an  additional  random  element  into  play. 

A  pseudo-random  seed  is  stored  by  the  following  function: 

RND<-TI)  Store  pseudo-random  seed 

RND(O)  can  be  used  to  store  a  new  seed  that  is  more  truly  random  by 
using  the  following  function: 

RND<-RND<0) )      Store  random  seed 
RSPCOLOR 

System  variable  that  contains  the  numeric  value  of  the  sprite  multi-color 
registers.  The  options  are 

1  =  multi-color  1 
2=  multi-color  2 

Example: 

PRINT  RSPCOLOR (1) 
12 

indicates  that  multi-color  2  is  dark  gray.  The  color  values  range  from  1  to  16. 
RSPPOS 

System  variable  that  contains  the  numeric  value  corresponding  to  the 
selected  sprite  position  and/ or  speed.  The  options  are 

0=X  position  of  sprite 
1  =  Y  position  of  sprite 
2=  Speed  of  sprite  (0-15) 

Example: 

PRINT  RSPPOS  (1,2) 
12 
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indicates  that  sprite  #1  is  moving  at  a  speed  of  12. 
RSPRITE 

System  variable  that  contains  the  sprite  data  (assigned  in  a  SPRITE 
statement)  of  the  selected  sprite.  The  options  are 

0=  SPRITE  ON/ OFF 

1  =  SPRITE  COLOR 

2  =  PRIORITY 

3  =  X  Expanded 

4  =  Y  Expanded 

5  -  Multi-color  mode 

RWINDOW 

System  variable  that  contains  the  current  window  information.  The 
options  are 

0  =  #  lines  in  current  window 

1  =  #  rows  in  current  window 

2  =  40/80-column  mode 

SGN 

SGN  determines  whether  a  number  is  positive,  negative,  or  zero. 

Format: 

SGN(arg  n) 

The  SGN  function  returns  +1  if  the  number  is  positive  or  nonzero,  0  if 
the  number  is  zero,  or  —1  if  the  number  is  negative. 

Example: 

?SGN<-6)  Displays -1 

?SGN<0)  Displays  0 

?S0N<44)  Displays  1 

IF  R>C  THEN  SR»SGN<X> 

IF  SGN(M)>«0  THEN  PRINT  "POSITIVE  NUMBER" 

SIN 

SIN  returns  the  sine  of  the  argument. 
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Sm(arg  n) 

Example: 

fl*SIN<flO> 

?3IN<45#tT/180)  Displays  the  sine  of  45  degrees 

SPC 

SPC  moves  the  cursor  right  a  specified  number  of  positions. 
Format: 

SVC(byte) 

The  SPC  function  is  used  in  PRINT  statements  to  move  the  cursor  some 
number  of  character  positions  to  the  right.  Text  over  which  the  cursor  passes 
is  not  modified. 

The  SPC  function  moves  the  cursor  right  from  whatever  column  the 
cursor  happens  to  be  in  when  the  SPC  function  is  encountered.  This  is  in 
contrast  to  a  TAB  function,  which  moves  the  cursor  to  some  fixed  column 
measured  from  the  leftmost  column  of  the  display.  (See  TAB  for  examples.) 

SQR 

SQR  returns  the  square  root  of  a  positive  number.  A  negative  number 
returns  an  error  message. 

Format: 

SQR(arg  n) 

Example: 

fl*SQR  <  4  )  Results  in  A=  2 

fl=SQR<4. 84)  Results  in  A=2.2 

?SQR<144E30)  Displays  1.2E+16 

ST 


ST  returns  the  current  value  of  the  1/  O  status.  This  status  is  set  to  certain 
values  depending  on  the  results  of  the  last  input/ output  operation. 
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Format: 
ST 

ST  values  are  shown  in  Table  F-l. 

Status  should  be  checked  after  execution  of  any  statement  that  accesses 
an  external  device. 

Example: 

10  IF  STO0  GOTO  500  Branch  on  any  error 

50  IF  ST*4  THEN  ?" SHORT  BLOCK" 

STR$ 

STRS  returns  the  string  equivalent  of  a  numeric  argument. 

Format: 

STR$(arg  n) 

STRS  returns  the  character  string  equivalent  of  the  number  generated  by 
resolving  arg  n. 

Example: 

fl**STR$<14.6>  Displays  14.6 
?fl$ 

?STR$<1E2)  Displays  100 

?STR$  <  1 E 1 0 )  Displays  1E+10 


TABLE  M.  ST  Values  for  I/O  Devices 


ST  Bit 
Position 

ST  Numeric 
Value 

Cassette 
Tape  Read 

Cassette  Tape 
Verify  and  Load 

0 
1 
2 
3 
4 

5 
6 

7 

1 

2 
4 
8 
16 

32 
64 
128 

Short  block 
Long  block 
Unrecoverable 

read  error 
Checksum  error 
End  of  file 
End  of  tape 

Short  block 
Long  block 
Any  mismatch 

Checksum  error 
End  of  tape 
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SYS 

SYS  is  a  system  function  that  transfers  program  control  to  an  indepen- 
dent subsystem. 

Format: 

SYS(mem  adr) 

mem  adr  is  the  starting  address  at  which  execution  of  the  subsystem  is  to 
begin.  The  value  must  be  in  the  range  0  <address  <65535. 

TAB 

TAB  moves  the  cursor  right  to  the  specific  column  position. 

Format: 

TAB(arg  n) 

TAB  moves  the  cursor  to  the  n+1  position,  where  n  is  the  number 
obtained  by  resolving  arg  n. 

Example: 

?"QURRK";SPC(10);  "W"  These  two  examples  show  the  difference  between  SPC 

QUARK               W  and  TAB.  SPC  skips  ten  positions  from  the  last 

?"QUflRKn;TAB<10);  "W"  cursor  location,  whereas  TAB  skips  to  the  10+  1th 

QUARK         Id  position  on  the  row 

TAN 

TAN  returns  the  tangent  of  the  argument. 

Format: 

TAN(arg  ri) 

Example: 

?TflN<3. 2)  Displays  0.0584738547 

XVa)»TAN<180#tr/180> 

Tl,  Tl$ 

TI  and  TI$  represent  two  system  time  variables. 
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Format: 

TI     Number  of  jiffies  since  current  startup 
TI$    Time  of  day  string 

Example: 
?TI 

TI$«"081000" 

USR 

US R  is  a  system  function  that  passes  a  parameter  to  a  user-written 
assembly  language  subroutine  whose  address  is  contained  in  memory  loca- 
tions 1  and  2.  USR  also  fetches  a  return  parameter  from  the  subroutine. 

Format: 

USR(arg) 

VAL 

VAL  returns  the  numeric  equivalent  of  the  string  argument. 

Format: 

VAL(data$) 

The  number  returned  by  VAL  may  be  used  in  arithmetic  computations. 

VAL  converts  the  string  argument  by  first  discarding  any  leading  blanks. 
If  the  first  nonblank  character  is  not  a  numeric  digit  (0-9),  the  argument  is 
returned  as  a  value  of  0.  If  the  first  nonblank  is  a  digit,  VAL  begins  converting 
the  string  into  real  number  format.  If  it  subsequently  encounters  a  nondigit 
character,  it  stops  processing  so  that  the  argument  returned  is  the  numerical 
equivalent  of  the  string  up  to  the  first  nondigit  character. 

Example: 

fl-VflL<"123") 
NN«VftL<B$) 
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XOR 

Logical  function  XOR.  Returns  a  value  that  corresponds  to  the  logical 
XOR'ed  value  of  two  numbers. 

Example: 

PRINT  XOR  (8,9) 
1 


Index 


A 

A  Complete  Joystick  Scanner,  156 
ABS,  109,  507 
Access,  414 

Accessing  the  Built-in  Character  Set,  198 

Accessing  the  Clock,  143 

Adding  Color  to  Your  Display,  173 

Addition,  67 

Addresses,  57 

Advanced  Editing  Functions,  114 
Alphabetic  Keys,  7 
Ambiguous  File  References,  346 
AND,  71 

Animating  Players,  198 
Animating  Sprites,  234 
Animating  Your  Players,  179 
Answer,  312 
APL,  56 
Archive,  412 
Arguments,  108 
Arithmetic  Calculations,  41 
Arithmetic  Functions,  109 


Arithmetic  Operators,  66 
Arrays,  74 
ASC,  110,  507 
Assembly  Language,  324 
Assigning  Output  to  the  Printer,  367 
Assignment  Statements,  82 
ATN,  109,  508 

Attack/ Decay  Control  Register,  431 

Attack/ Sustain/ Decay,  261 

Attacks  Using  the  Built-in  Functions,  264 

AUTO,  114,  462 

AUXIN:,  404 

B 

Backspacing  With  the  Delete  Key,  40 

Backup,  462 

Bam,  302 

Bank,  462 

Base  2,  324 

Base  3,  324 

Base  10,  324 

Base  16,  324 
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BASIC  Commands,  77 

BASIC  Statements,  81 

BASIC  Word  Abbreviations,  80 

Baud  Rate,  312 

BDOS  ERR,  355 

Beat  Frequency,  266 

BEGIN,  463 

Bells  and  Whistles,  239 

BEND,  463 

Binary,  324 

Bit-Mapped  Graphics  Shapes,  214 
BLOAD,  463 

BLOCK-ALLOCATE,  302 
BLOCK-FREE,  306 
BLOCK-READ,  300 
BLOCK-WRITE,  304 
Boolean  Operators,  71 
Boot,  339,  463 

Border,  Background,  and  Character 

Colors,  167 
BOX,  215,  463 
Branch  Statements,  86 
BREAK,  107,  340 
BSAVE,  464 
Buffer-Pointer,  305 
Built-in  Commands,  349,  351 
Bump,  508 

C 

C-128  Mode  Bit-Mapped  Graphics,  213 
C-128  Mode  Sprite  Graphics,  238 
C-128  Special  Sound  and  Music 

Features,  277 
C-64  Mode  Bit-Mapped  Graphics,  204 
C-64  Mode  Sprite  Graphics,  217 
CP/M,  339 
CAL,  342 

Cancel  Current  Command,  368 
Care  of  Cassette  Tapes,  25 
Care  of  Diskettes,  30 
Cassette  Data  File  Format,  491 
Cassette  Interface,  4 
Cassette  Motor  Interlock,  425 
Cassette  Program  Format,  487 
Cassette  Tape  Write-Protect,  25 
CATALOG,  464 
Change  Default  Disk  Drive,  362 


Changing  the  Dots  in  the  Bit-Mapped 

Work  Area,  206 
Changing  the  Sound,  278 
Channel  Number,  53 
CHAR,  217,  464 
Character  Memory,  186 
Choosing  the  Keys,  161 
CHR$,  110,  509 
CIRCLE,  214,  464 
Cleaning  and  Demagnetizing,  23 
CLEAR  HOME,  14 
CLOSE,  314,  465 
CLOSE  Statement,  53 
Closing  Disk  Files,  299 
CLR,  465 
CMD,  314,  465 
CMD  Statement,  52 
COBOL,  56 
Cold  Boot,  361 
Collect,  466 
Collision,  466 
Colon,  83 
COLOR,  467 
COLOR  Command,  168 
Color  Control  Keys,  13 
Color  Memory,  175 
Coloring  Sprites,  239 
Combining  Commands,  386 
Combining  Filename  and  File  Type,  344 
Combining  PRINTed  and  POKEd 

Graphics,  181 
Combining  Sound  With  Animation,  276 
Comma,  316 
Commas,  99 
Composite  Video,  4 
Computed  GOSUB  Statement,  97 
Computed  GOTO  Statement,  88 
Components  of  Sound,  257 
CONCAT,  468 
Concatenating  Strings,  115 
Concatenation,  63 
CONFIRM,  356 
Connecting  Disk  Drives,  26 
Connecting  the  Printer,  31 
Console,  403 
CONT,  107,  468 

Contents  of  Color  Memory,  176 
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Context  Editor,  374 
Control  Statements,  89 
Control-Character 

(Line-Editing),  363 
Controllers,  158 
COPY,  469 
Copying  Files,  296 
Copying  Information,  386 
COPYSYS,  420 
COS,  109,  509 
CP/M  Master  Disk,  339 
CP/M  Transient  Commands,  369 
CP/M  Utility  Programs,  419 
CP/M's  Built-in  Commands,  349 
CREATE,  414 

Creating  a  Formatted  Display,  124 

Creating  Displays  With  POKE,  174 

Creating  Music  Arrays,  274 

ctrl-c,  364 

Cursor,  38,  364 

Cursor  Control  Keys,  14 

Cursor  Keys,  340 

Cursor  Movement,  124 

Cursor  Up/ Down,  16 

Custom  Character  Sets,  186 

C-128  Computer,  1 

C-128  Electronic  Organ,  273 

C-128  Screen,  166 

D 

Data,  58,  469 

Data  and  Read  Statements,  84 
Data  Entry  (Input),  127 
DATA  Entry  Sequence,  135 
Data  Entry  Subroutines,  139 
DATA  Statements,  84 
Data  Transfer,  284 
Datassette,  20,  44 
Datassette  Files,  285 
DATE,  401 
DCLEAR,  470 
DCLOSE,  470 
DEC,  509 
Decay,  261 

Decays  Using  the  Built-in  Functions,  263 
Decimal,  324 
DEF  FN,  111,  470 


Default,  414 
DEL,  340 

DELETE,  114,  340,  471 

Design  Aids  for  Custom  Characters,  196 

Designing  a  Sprite,  238 

Designing  Characters,  192 

Designing  Sprites,  224 

Designing  the  Interface  to  the  Main 

Program,  161 
Detecting  Collisions  in  C-128  Mode,  249 
Detecting  Collisions  in  C-64  Mode,  246 
Device,  402 
DIM,  86,  472 
Dimension  Statement,  86 
DIR,  350 
Directory,  473 
DIRSYS,  351 

Disk  Data  File  Format,  492 

Disk  Data  Files,  297 

Disk  Drive  Identifiers,  345 

Disk  File  Concatenation,  296 

Disk  Files,  292 

Disk  Label,  411 

Disk  Utility  Instructions,  300 

Diskette  Directory,  292 

Diskette  Drive  Format,  499 

Diskette  Drive  Program  Format,  487 

Diskette  Sectoring,  292 

Diskette  Write-Protection,  30 

Display  Priorities,  242 

Display  the  System  File  Directory,  351 

Displaying  the  Contents  of  a  File,  372 

Division,  69 

DLOAD,  473 

DOPEN,  474 

Double/ Single-Width  Characters,  318 
DRAW,  215,  474 
DSAVE,  475 
DUMP,  372 

E 

ECHO,  405 

Echoing  Keystrokes,  160 
ED,  374 
ED.COM,  374 

Editing  Data  Entry  Lines,  138 
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Editing  Text  Between  Quotation 

Marks,  41 
Editing  Text  on  the  Current 

Display  Line,  39 
Editing  the  Sprite,  238 
Elements  of  a  Programming 

Language,  55 
Enabling  and  Disabling  Sprites,  230 
END,  107,  475 
Ending  the  Edit,  239 
Entering  a  Valid  Date,  129 
ENVELOPE,  279,  475 
EOF,  388 

ERA,  346,  350,  356 
ERASE,  356 
Erasing  Files,  295 
ERRS,  509 

Error  and  Advisory  Messages,  348 
ESC,  340 
EXIT,  476 
EXP,  109,  510 
Expansion  Interface,  4 
Exploring  Character  Memory,  191 
Exponentiation,  69 

F 

Fading  Tones,  261 
FAST,  476 
FETCH,  476 
Fields,  341 

File  and  Drive  Attributes,  411 
FILE  EXISTS,  359 
File  Types,  342 
Filenames,  341 
Files,  282,  340 
Filter,  410,  476 

Finding  a  Character's  Definition  in 

Character  Memory,  190 
Finding  Color  Memory,  176 
Finding  Screen  Memory,  174 
Floating-Point  Numbers,  58 
Floppy  Disks,  30 
FNxx,  510 

FOR-NEXT  Statement,  89 
FOR-NEXT  STEP,  476 
FORMAT,  419 

Format  of  Character  Memory,  187 
Formatted  Data  Input,  134 


Formatting,  101 

Formatting  a  Diskette,  48,  294 

FORTH,  56 

FORTRAN,  56 

FRE,  111,  510 

Full/  Half  Duplex,  312 

Function,  340 

Function  Keys,  10 

Functions,  107 

G 

Game  Controllers,  151 
Game  Ports,  3 

Generating  Random  Dice  Throws,  148 

GET,  405,  478 

GET  Statement,  105 

GET  Statement  Syntax,  160 

GET#,  478 

GETKEY,  478 

G064,  479 

GOSUB,  479 

GOSUB  Statement,  95 

GOTO,  480 

GOTO  Statement,  87 

GRAPHIC,  480 

Graphic  Keys,  8 

Graphics  Screens,  213 

Graphics,  319 

Graphics  Repeat  Function,  321 
Graphics  With  the  Extended  Character 
Set,  169 

H 

Handshaking,  312 
Header,  480 
HELP,  340,  407,  481 
HEX$,  511 
Hexadecimal,  324 
Hexadecimal-Decimal  Integer 

Conversion,  443 
Housekeeping  Utilities,  371 
How  Characters  Are  Displayed,  186 
How  Data  Is  Stored  on  Diskette,  292 
How  Sprites  Are  Displayed,  222 
How  to  Handle  Memory  Loss,  197 

I 

I/O  PINOUTS,437 
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ID  Number,  48 

IF-THEN,  481 

IF-THEN  Statement,  97 

ILLEGAL  COMMAND  TAIL,  355 

Immediate  Mode,  38 

Indicator  Lights,  27 

INITDIR,  409 

Initialization,  48,  294 

Initialization  Process,  5 

Initialize,  482 

INPUT,  483 

Input  and  Output  Programming,  121 
INPUT  Statement,  103 
INPUT#,  484 

Input/ Output  Statements,  98 
INS/ DEL,  135,  366 
INSERT,  340 
INSERT/  DELETE,  18 
Installing  the  Modem,  311 
Installing  the  Ribbon,  33 
INSTR,  511 
INT,  109,  511 
Integer  Variables,  76 
Integers,  62 

Interpreting  Pointers,  423 
J 

Jiffies,  144 

Jiffy  Clock,  424 

JOY,  512 

Joystick,  151 

Joystick  Controller,  152 

K 

KEY,  485 

Keyboard  Buffer,  425 
Keyboard,  7 

Keyboard  Communication  Using  the 

GET  Statement,  159 
Keyboard  as  Joystick,  161 
Keyboard  Interpreter  Subroutine,  162 

L 

LEFTS,  110,  512 
LEN,  110,  513 
LET,  83 
LET=,  485 
Line  Numbers,  56 


LIST,  408,  485 

LOAD,  283,  350,  486 

LOAD  and  RUN,  47 

Loading  a  Program,  45,  47 

Loading  and  Unloading  Diskettes,  27 

Loading  the  Drive,  29 

Loading  the  Tables,  162 

Loading  Your  Sprite  Definition  Into 

Memory,  227 
LOCATE,  488 
LOG,  109,  513 

Logical  Files  and  Physical  Units,  284 
Loop,  93 

M 

Machine  Language  Monitor,  324 

Machine  Language  Programming,  322 

Memory  Segments,  185 

Memory-Execute,  309 

Memory- Read,  309 

Memory- Write,  307 

Messages  From  the  System,  347 

MID$,  110,  514 

Mixing  Tones,  265 

Mnemonics,  324 

Modem,  311,  312 

Modulated  (TV)  Video,  4 

Monitor,  488 

More  Complex  Animation,  201 

Moving  Around  in  the  Sprite  Editor,  238 

Moving  Your  Sprite,  231 

MOVSPR,  488 

MPS  803,  4 

Multiple  Tones,  259 

Multiple-Disk  Systems,  296 

Multiplication,  68 

N 

Nested  Loops,  91 
Nested  Subroutines,  96 
NEW,  489 

NEW  (DOS  Command),  489 

NO  ECHO,  406 

NO  FILE,  359 

NO  FILTER,  410 

NO  PAGE,  407 

NOXON,  404 

NUL,  388 
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NUMBERS,  324,  341 
Numeric  Keys,  8 
Numeric  Strings,  117 

O 

Octal,  324 

ON-GOSUB,  490 

ON-GOTO,  490 

OPEN,  49,  285,  314,  491 

OPEN  Statement,  51 

Operating  the  1571  Disk  Drive,  47 

Operating  the  MPS  803  Graphic 

Printer,  51 
Operators,  66 
OR,  71 

Order  of  Evaluation,  70 
Originate,  312 
OVR,  342 

P 

PAINT,  216,  493 

Paper  Insertion,  34 

Parallel  User  Port,  3 

Parity,  313 

Pascal,  56 

Password,  411 

PEEK,  106,  111,514 

PEEK  and  POKE  Statements,  106 

PEN,  514 

Peripheral  Interchange  Program,  386 

PIP,  386 

PL- 1,56 

PL/M,  56 

PLAY,  278,  493 

PLAY  and  RECORD,  23 

Players  and  Playfields,  169 

Pointer,  174,  515 

POKE,  106,  493 

POLYGONS,  215 

POS,  317,  515 

POS  Function,  102 

Pot,  158,  516 

Potentiometer,  158 

Power  Connector,  3 

Power  supply,  1 

Power  Switch,  2 

POWER  UP,  5 


Power-On  Test,  26 

"Presetting"  the  Response  to  Input,  105 
PRINT,  493 

PRINT  Field  Formats,  494 

PRINT  Formats,  494 

Print  Formatting,  316 

Print  Formatting  Functions,  101 

PRINT  Statement,  98 

PRINT#,  52,  299,  495 

PRINT#  Output  to  Cassette  Files,  495 

PRINT#  Output  to  Diskette  Files,  495 

PRINT#  Output  to  the  Line  Printer,  496 

Printer,  4 

Printer  Graphics,  318 
Printing  a  Directory,  473 
Printing  a  Program  Listing,  486 
PRN,  388 
Program  Entry,  42 
Program  Files,  282 
PROGRAM  Mode,  42 
Programmable  Function  Keys,  19 
Programming  Characters  in  ASCII,  125 
Programming  Cursor  Movement,  124 
Programming  Music  on  the  C-128,  268 
Programming  Rhythm,  272 
Programming  the  Function  Keys,  19 
Programming  With 

Strings,  115 
Prompting,  104 
Prompting  Messages,  128 
Prompts,  347 
PROTECT,  413 
Protective  Jacket,  27 
Pulsed  Tones,  259 
Pure  Tones,  257 
PUT,  409 

Putting  Your  Sprite  to  Work,  226 
€fc 

Question  Mark,  103 
Quotation  Mark,  100 
Quote  Mode,  41 
Quotes  in  Strings,  100 

R 

Racetrack  Game,  181 
Random  Access  Files,  299 
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Random  Numbers,  147 

Random  Selection  of  Playing  Cards,  149 

RCLR,  516 

RDOT,  5 17 

READ,  496 

READ  Statement,  84 

Reading  a  Data  File,  299 

Reading  Data  Files,  289 

Reading  Music  From  the  Datassette 

or  Disk,  275 
Reading  the  Joysticks  in  C-128  Mode,  157 
Real-Time  Clock  Operation,  144 
Rear  and  Side  Panel,  2 
Recall  and  Display  Previously  Entered 

Command  Line,  369 
Records,  341 
Records  and  Fields,  283 
REDO  FROM  START,  103 
Relational  Expressions,  74 
Relational  Operations,  70 
REM,  82,  497 
Remarks,  82 
REN,  350,  358 
RENAME,  358 
Renaming  Files,  295 
RENUMBER,  115,  497 
Repeat  Delay,  425 
Repeat  Key,  425 
Repeat  Rate,  425 
Reserved  Words,  78 
RESET,  364 
Restart  CP/M,  364 
RESTORE,  13,  85,  497 
RESTORE  Statement,  85 
RETURN,  11,498 
Reverse  Characters,  319 
Reverse  On/ Off,  12 
RGB,  4 
RGR,  517 
RIGHTS,  110,  517 
RND,  109,  517 
RO,  412 
Roundoff,  59 
RSPCOLOR,  517 
RSPPOS,  518 
RSPRITE,  519 
RUN,  498 


RUN/ STOP,  12 
Running  a  Program,  43 
RW,  412 

RWINDOW,  519 
S 

SAVE,  350,  499 

Saving  a  Program,  44,  49 

Saving  Music,  274 

Saving  Sprite  Definitions,  239 

SCALE,  216,  500 

Scientific  Notation,  60 

SCNCLR,  500 

SCRATCH,  500 

Screen  Display  Codes,  177 

Screen  Editing,  39 

Screen  Layout,  122 

Screen  Memory,  174,  425 

Screen  Memory  Layout,  175 

Selecting  Waveforms,  266 

Semicolon,  99,  317 

Sequential  Files,  297 

Serial  Port,  4 

SET,  411 

SETDEF,  415 

Setting  the  Clock,  143 

Setting  up  the  Voice  Control 

Registers,  253 
SGN,  109,  519 
SHIFT,  10 
SHIFT  LOCK,  11 
SHIFT-RETURN,  170 
Shifting  and  Deleting  Text  With  the 

Delete  Key,  40 
Shifting  Text  to  Insert  Characters,  40 
SHOW,  417 
SID  Chip,  158 

SID  Chip  Control  Registers,  431 

SIN,  109, 519 

Sleep,  501 

SLOW,  501 

Soft-Sectored,  28 

SOUND,  277,  501 

Sound  and  Display  Characters  and 

Codes,  451 
SPC,  101,317,  520 
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Special  Symbol  Keys,  8 
SPRCOLOR,  502 
SPRDEF,  502 
SPRITE,  502 
Sprite  Interaction,  242 
Sprite  Memory,  223 
SQR,  109,  520 
ST,  520 

Start/ Stop  Bits,  313 

Status  Register,  289 

STOP,  107,  502 

STOP/ EJECT,  23 

Storing  Data,  281 

Storing  Music,  275 

STR$,  110,  521 

String  Functions,  110 

STRING  TOO  LONG  Error,  68 

STRINGS,  62 

SUBMIT,  398 

Subroutine,  94 

Subroutine  Statements,  94 

Subtraction,  68 

Sustain,  261,  264 

Sweeping  the  Scales,  258,  277 

Syntax,  38,  55 

SYS,  111,  522 

SYSTEM,  406 

System  Functions,  111 

T 

TAB,  317,  340,  522 
TAB  Function,  101 
TAN,  109,  522 

Telling  the  VIC-II  Chip  Where  to  Find 

Your  Sprite,  227 
Tempo,  279,  502 
Terminology,  312 
Testing  the  Datassette,  22 
Testing  the  Joystick  Switches,  154 
TI,  111 
TI$,  111 
TI,  TI$,  522 
Time  Stamping,  411 
Timing,  276 

Transient  Commands,  349 
TV  Switch  Box,  1 
TYPE,  350,  359 


U 

Ul,  310 
U2,  310 
U3-U9,  310 
Unary  Minus,  68 
Unloading  the  Drive,  29 
Unpause  Display,  368 
UPDATE,  414 
USER,  350,  361 
USER  Commands,  310 
User-Defined  Functions,  111 
Using  GET#  to  Read  Files,  291 
Using  Reversed  Characters,  172 
Using  String  Variables  as  File 

Names,  298 
Using  the  Datassette,  44 
Using  the  Entire  Screen,  211 
Using  the  Joystick  Scanner,  157 
Using  the  Keyboard  Joystick,  163 
Using  the  Noise  Register,  268 
Using  Your  Characters  on  the  C-128,  194 
USR,  111,  523 

V 

VAL,  110,  523 
VALIDATE,  295,  503 
Variable  Names,  64 
Variables,  63 
Verification,  45 
VERIFY,  503 
VIA,  155 

Vibrato/ Tremolo,  265 

VIC  II  Chip  Control  Registers,  426 

VIC-II,  166 

Video  Cable,  1 

Video  Display,  5 

Video  Interface,  166 

Video  Ports,  4 

Voice  Control  Registers,  253 

VOL,  504 

Volume  Adjustments,  261 
W 

WAIT,  505 
Warm  Boot,  364 
Wildcard  References,  346 
WINDOW,  505 


Words,  341 
Wraparound,  18 
Write-Protect,  23 
Writing  Data  Files,  287 
Writing  Programs  That  Make  Use 
Custom  Characters,  197 
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X 

XON,  404 
XON/XOFF,  404 
XOR,  524 
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